docs: document infra package helpers

steipete · steipete · commit 334a1dd71698 · 2026-06-04T02:58:15.000-04:00
diff --git a/src/infra/approval-handler-bootstrap.ts b/src/infra/approval-handler-bootstrap.ts
@@ -1,3 +1,4 @@
+// Bootstraps approval handlers from channel plugin capabilities.
 import { resolveChannelApprovalCapability } from "../channels/plugins/approvals.js";
 import type { ChannelRuntimeSurface } from "../channels/plugins/channel-runtime-surface.types.js";
 import type { ChannelPlugin } from "../channels/plugins/types.plugin.js";
diff --git a/src/infra/archive-path.ts b/src/infra/archive-path.ts
@@ -1,3 +1,4 @@
+// Resolves archive paths through safe filesystem defaults.
 import "./fs-safe-defaults.js";
 
 // Archive path facade kept in infra so callers share one traversal policy.
diff --git a/src/infra/brew.test.ts b/src/infra/brew.test.ts
@@ -1,3 +1,4 @@
+// Tests Homebrew discovery and metadata parsing helpers.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/infra/channel-approval-auth.test.ts b/src/infra/channel-approval-auth.test.ts
@@ -1,3 +1,4 @@
+// Tests channel approval authorization and sender validation.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createResolvedApproverActionAuthAdapter } from "../plugin-sdk/approval-auth-helpers.js";
 
diff --git a/src/infra/control-ui-assets.test.ts b/src/infra/control-ui-assets.test.ts
@@ -1,3 +1,4 @@
+// Tests Control UI asset discovery and expected bundled files.
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/infra/dotenv-global.ts b/src/infra/dotenv-global.ts
@@ -1,3 +1,4 @@
+// Loads global dotenv files into process environment when requested.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/errors.test.ts b/src/infra/errors.test.ts
@@ -1,3 +1,4 @@
+// Tests shared infra error formatting and classification.
 import { describe, expect, it } from "vitest";
 import {
   collectErrorGraphCandidates,
diff --git a/src/infra/exec-safe-builtins.test.ts b/src/infra/exec-safe-builtins.test.ts
@@ -1,3 +1,4 @@
+// Tests shell builtin detection for safe execution policy.
 import { describe, expect, it } from "vitest";
 import { evaluateExecAllowlist, evaluateShellAllowlist } from "./exec-approvals-allowlist.js";
 import { analyzeArgvCommand } from "./exec-approvals-analysis.js";
diff --git a/src/infra/fs-safe.test.ts b/src/infra/fs-safe.test.ts
@@ -1,3 +1,4 @@
+// Tests safe filesystem wrappers and protected file-handle behavior.
 import type { FileHandle } from "node:fs/promises";
 import fs from "node:fs/promises";
 import path from "node:path";
diff --git a/src/infra/gateway-discovery-targets.ts b/src/infra/gateway-discovery-targets.ts
@@ -1,3 +1,4 @@
+// Normalizes gateway discovery targets for local and remote lookups.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   resolveGatewayDiscoveryEndpoint,
diff --git a/src/infra/heartbeat-runner.returns-default-unset.test.ts b/src/infra/heartbeat-runner.returns-default-unset.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat runner behavior when defaults are unset.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/npm-integrity.test.ts b/src/infra/npm-integrity.test.ts
@@ -1,3 +1,4 @@
+// Tests npm integrity parsing and drift detection.
 import { describe, expect, it, vi } from "vitest";
 import {
   resolveNpmIntegrityDrift,
diff --git a/src/infra/npm-integrity.ts b/src/infra/npm-integrity.ts
@@ -1,3 +1,4 @@
+// Resolves npm integrity metadata and detects package drift.
 import type { NpmIntegrityDrift, NpmSpecResolution } from "./install-source-utils.js";
 
 /** Payload passed to npm integrity drift handlers during archive installs. */
diff --git a/src/infra/npm-pack-install.ts b/src/infra/npm-pack-install.ts
@@ -1,3 +1,4 @@
+// Installs packages from npm pack artifacts for smoke and release checks.
 import {
   type NpmIntegrityDrift,
   type NpmSpecResolution,
diff --git a/src/infra/npm-registry-spec.ts b/src/infra/npm-registry-spec.ts
@@ -1,3 +1,4 @@
+// Parses npm registry specs into package, version, and tag references.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 const EXACT_SEMVER_VERSION_RE =
diff --git a/src/infra/path-safety.ts b/src/infra/path-safety.ts
@@ -1,3 +1,4 @@
+// Exposes path-safety helpers backed by fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Back-compat import path for path guard helpers used across core surfaces.
diff --git a/src/infra/ports-probe.ts b/src/infra/ports-probe.ts
@@ -1,3 +1,4 @@
+// Probes local ports and reports listener availability.
 import net from "node:net";
 
 /** Opens and closes a temporary listener to verify that a port can be bound. */
diff --git a/src/infra/provider-usage.fetch.deepseek.ts b/src/infra/provider-usage.fetch.deepseek.ts
@@ -1,3 +1,4 @@
+// Fetches and normalizes DeepSeek provider usage records.
 import {
   buildUsageHttpErrorSnapshot,
   fetchJson,
diff --git a/src/infra/restart-sentinel.ts b/src/infra/restart-sentinel.ts
@@ -1,3 +1,4 @@
+// Persists restart sentinel files that coordinate deferred restarts.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { isRecord as isPlainRecord } from "@openclaw/normalization-core/record-coerce";
diff --git a/src/infra/runtime-status.ts b/src/infra/runtime-status.ts
@@ -1,3 +1,4 @@
+// Normalizes runtime status values for CLI and gateway reporting.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 type RuntimeStatusFormatInput = {
diff --git a/src/infra/ssh-tunnel.ts b/src/infra/ssh-tunnel.ts
@@ -1,3 +1,4 @@
+// Starts and monitors SSH tunnels for remote gateway access.
 import { spawn } from "node:child_process";
 import net from "node:net";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
diff --git a/src/infra/system-presence.ts b/src/infra/system-presence.ts
@@ -1,3 +1,4 @@
+// Detects system command availability for setup and diagnostics.
 import { spawnSync } from "node:child_process";
 import os from "node:os";
 import {
diff --git a/src/infra/update-control-plane-sentinel.ts b/src/infra/update-control-plane-sentinel.ts
@@ -1,3 +1,4 @@
+// Persists update-control-plane sentinel files used by updater coordination.
 import fs from "node:fs/promises";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import {
diff --git a/src/infra/widearea-dns.test.ts b/src/infra/widearea-dns.test.ts
@@ -1,3 +1,4 @@
+// Tests wide-area DNS discovery parsing and timeout behavior.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Bootstraps approval handlers from channel plugin capabilities.`
`1`	`2`	`import { resolveChannelApprovalCapability } from "../channels/plugins/approvals.js";`
`2`	`3`	`import type { ChannelRuntimeSurface } from "../channels/plugins/channel-runtime-surface.types.js";`
`3`	`4`	`import type { ChannelPlugin } from "../channels/plugins/types.plugin.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Resolves archive paths through safe filesystem defaults.`
`1`	`2`	`import "./fs-safe-defaults.js";`
`2`	`3`
`3`	`4`	`// Archive path facade kept in infra so callers share one traversal policy.`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests Homebrew discovery and metadata parsing helpers.`
`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 channel approval authorization and sender validation.`
`1`	`2`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { createResolvedApproverActionAuthAdapter } from "../plugin-sdk/approval-auth-helpers.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests Control UI asset discovery and expected bundled files.`
`1`	`2`	`import path from "node:path";`
`2`	`3`	`import { pathToFileURL } from "node:url";`
`3`	`4`	`import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Loads global dotenv files into process environment when requested.`
`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`	`+// Tests shared infra error formatting and classification.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`collectErrorGraphCandidates,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests shell builtin detection for safe execution policy.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { evaluateExecAllowlist, evaluateShellAllowlist } from "./exec-approvals-allowlist.js";`
`3`	`4`	`import { analyzeArgvCommand } from "./exec-approvals-analysis.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests safe filesystem wrappers and protected file-handle behavior.`
`1`	`2`	`import type { FileHandle } from "node:fs/promises";`
`2`	`3`	`import fs from "node:fs/promises";`
`3`	`4`	`import path from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Normalizes gateway discovery targets for local and remote lookups.`
`1`	`2`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import {`
`3`	`4`	`resolveGatewayDiscoveryEndpoint,`