docs: document infra install helpers

src/infra/approval-gateway-resolver.ts

@@ -1,3 +1,4 @@
+// Resolves exec and plugin approvals through the gateway client.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { withOperatorApprovalsGatewayClient } from "../gateway/operator-approvals-client.js";
 import { isApprovalNotFoundError } from "./approval-errors.js";

src/infra/clawhub.ts

@@ -1,3 +1,4 @@
+// Fetches and validates ClawHub package metadata and artifacts.
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";

src/infra/diagnostic-flags.ts

@@ -1,3 +1,4 @@
+// Resolves diagnostics feature flags from config and environment.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntriesLower } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/infra/diagnostics-timeline.ts

@@ -1,3 +1,4 @@
+// Records structured diagnostics timeline events and spans.
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";

src/infra/exec-approval-surface.ts

@@ -1,3 +1,4 @@
+// Resolves native approval support for the initiating channel surface.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   getChannelPlugin,

src/infra/fetch-headers.test.ts

@@ -1,3 +1,4 @@
+// Covers request header normalization before fetch calls.
 import { describe, expect, it } from "vitest";
 import {
   normalizeHeadersInitForFetch,

src/infra/fixed-window-rate-limit.test.ts

@@ -1,3 +1,4 @@
+// Covers fixed-window rate limiter boundaries.
 import { describe, expect, it } from "vitest";
 import { createFixedWindowRateLimiter } from "./fixed-window-rate-limit.js";
 

src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts

@@ -1,3 +1,4 @@
+// Covers heartbeat ack truncation limits.
 import fs from "node:fs/promises";
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";

src/infra/install-from-npm-spec.ts

@@ -1,3 +1,4 @@
+// Installs validated registry npm specs through archive install helpers.
 import type { NpmIntegrityDriftPayload } from "./npm-integrity.js";
 import {
   finalizeNpmSpecArchiveInstall,

src/infra/install-mode-options.ts

@@ -1,3 +1,4 @@
+// Resolves common install/update mode options.
 type InstallMode = "install" | "update";
 
 type InstallModeOptions<TLogger> = {

src/infra/install-safe-path.test.ts

@@ -1,3 +1,4 @@
+// Covers safe plugin install path normalization and boundary checks.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";

src/infra/install-safe-path.ts

@@ -1,3 +1,4 @@
+// Provides safe path helpers for plugin installation targets.
 import "./fs-safe-defaults.js";
 export {
   assertCanonicalPathWithinBase,

src/infra/node-pairing-authz.test.ts

@@ -1,3 +1,4 @@
+// Covers scope requirements for node pairing approvals.
 import { describe, expect, it } from "vitest";
 import { resolveNodePairApprovalScopes } from "./node-pairing-authz.js";
 

src/infra/openclaw-root.ts

@@ -1,3 +1,4 @@
+// Resolves the OpenClaw package root from runtime and package metadata.
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { openClawRootFs, openClawRootFsSync } from "./openclaw-root.fs.runtime.js";

src/infra/private-temp-workspace.ts

@@ -1,3 +1,4 @@
+// Exposes private temp workspace helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Private temp workspaces isolate downloads and generated artifacts under a

src/infra/provider-usage.fetch.shared.test.ts

@@ -1,3 +1,4 @@
+// Covers shared provider usage fetch parsing and error snapshots.
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withFetchPreconnect } from "../test-utils/fetch-mock.js";

src/infra/provider-usage.format.test.ts

@@ -1,3 +1,4 @@
+// Covers provider usage report formatting.
 import { describe, expect, it } from "vitest";
 import {
   formatUsageReportLines,

src/infra/regular-file.ts

@@ -1,3 +1,4 @@
+// Exposes regular-file IO helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Regular-file IO helpers reject symlinks and non-file targets before reads or

src/infra/session-delivery-queue-recovery.ts

@@ -1,3 +1,4 @@
+// Recovers queued session deliveries after process crashes.
 import {
   resolveDateTimestampMs,
   resolveExpiresAtMsFromDurationMs,

src/infra/system-run-approval-binding.test.ts

@@ -1,3 +1,4 @@
+// Covers system-run approval binding normalization and matching.
 import { describe, expect, it } from "vitest";
 import {
   buildSystemRunApprovalBinding,

src/infra/update-package-manager.test.ts

@@ -1,3 +1,4 @@
+// Covers package manager resolution for update build flows.
 import { describe, expect, it } from "vitest";
 import {
   resolveUpdateBuildManager,

src/infra/update-restart-sentinel-payload.ts

@@ -1,3 +1,4 @@
+// Builds restart sentinel payloads for update handoff reporting.
 import {
   buildRestartSuccessContinuation,
   formatDoctorNonInteractiveHint,

src/infra/windows-encoding.test.ts

@@ -1,3 +1,4 @@
+// Covers Windows command-output code page parsing and decoding.
 import { describe, expect, it } from "vitest";
 import {
   createWindowsOutputDecoder,

src/infra/wsl.test.ts

@@ -1,3 +1,4 @@
+// Covers WSL detection from platform and release files.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { captureEnv } from "../test-utils/env.js";
 import { mockProcessPlatform } from "../test-utils/vitest-spies.js";