docs: document plugin loader helpers

steipete · steipete · commit 6082f01b971e · 2026-06-04T04:27:23.000-04:00
diff --git a/src/plugins/agent-event-emission.ts b/src/plugins/agent-event-emission.ts
@@ -1,3 +1,4 @@
+// Emits agent events requested by plugin hook contracts.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { emitAgentEvent } from "../infra/agent-events.js";
 import {
diff --git a/src/plugins/api-facades.ts b/src/plugins/api-facades.ts
@@ -1,3 +1,4 @@
+// Builds plugin API facades exposed to bundled and external plugins.
 import type { OpenClawPluginApi } from "./types.js";
 
 type PluginApiFacadeFields = Pick<
diff --git a/src/plugins/bundled-dir.test.ts b/src/plugins/bundled-dir.test.ts
@@ -1,3 +1,4 @@
+// Verifies bundled plugin directory resolution.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/plugins/clawhub-install-records.ts b/src/plugins/clawhub-install-records.ts
@@ -1,3 +1,4 @@
+// Converts ClawHub plugin entries into install records.
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import type { ClawHubPackageChannel, ClawHubPackageFamily } from "../infra/clawhub.js";
 
diff --git a/src/plugins/clawhub.ts b/src/plugins/clawhub.ts
@@ -1,3 +1,4 @@
+// Resolves ClawHub plugin catalog entries and install metadata.
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/plugins/config-policy.test.ts b/src/plugins/config-policy.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin config policy validation and ownership decisions.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/plugins/copy-bundled-plugin-metadata.test.ts b/src/plugins/copy-bundled-plugin-metadata.test.ts
@@ -1,3 +1,4 @@
+// Covers copying bundled plugin metadata for package output.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/plugins/hooks.security.test.ts b/src/plugins/hooks.security.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin hook security constraints and rejections.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createHookRunner } from "./hooks.js";
 import { addStaticTestHooks } from "./hooks.test-helpers.js";
diff --git a/src/plugins/host-tool-param-parsers.ts b/src/plugins/host-tool-param-parsers.ts
@@ -1,3 +1,4 @@
+// Parses host tool parameters supplied by plugin tool contracts.
 import {
   extractApplyPatchTargetPaths,
   type ApplyPatchPathExtractionOptions,
diff --git a/src/plugins/install-source-info.test.ts b/src/plugins/install-source-info.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin install source info formatting and parsing.
 import { describe, expect, it } from "vitest";
 import { describePluginInstallSource } from "./install-source-info.js";
 
diff --git a/src/plugins/install.npm-spec.e2e.test.ts b/src/plugins/install.npm-spec.e2e.test.ts
@@ -1,3 +1,4 @@
+// Exercises npm-spec plugin install behavior through the CLI path.
 import { execFile, execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
diff --git a/src/plugins/install.path.test.ts b/src/plugins/install.path.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin install path validation and normalization.
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/plugins/installed-plugin-index-invalidation.ts b/src/plugins/installed-plugin-index-invalidation.ts
@@ -1,3 +1,4 @@
+// Invalidates installed plugin index entries after activation metadata changes.
 import { hasConfigPathActivationMetadataMigration } from "./installed-plugin-index-config-path-scope.js";
 import { hashJson } from "./installed-plugin-index-hash.js";
 import type {
diff --git a/src/plugins/installed-plugin-index-registry.ts b/src/plugins/installed-plugin-index-registry.ts
@@ -1,3 +1,4 @@
+// Builds plugin registry inputs from installed plugin index records.
 import { normalizePluginsConfig } from "./config-state.js";
 import {
   discoverOpenClawPlugins,
diff --git a/src/plugins/loader-sdk-import-guardrails.test.ts b/src/plugins/loader-sdk-import-guardrails.test.ts
@@ -1,3 +1,4 @@
+// Verifies loader guardrails for plugin SDK import boundaries.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts
@@ -1,3 +1,4 @@
+// Discovers, validates, and loads plugin metadata and runtime entrypoints.
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/plugins/model-catalog-registration.ts b/src/plugins/model-catalog-registration.ts
@@ -1,3 +1,4 @@
+// Registers plugin-provided models into the model catalog.
 import type {
   UnifiedModelCatalogEntry,
   UnifiedModelCatalogSource,
diff --git a/src/plugins/plugin-control-plane-context.test.ts b/src/plugins/plugin-control-plane-context.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin control-plane context construction and boundaries.
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/plugins/provider-auth-choice.test.ts b/src/plugins/provider-auth-choice.test.ts
@@ -1,3 +1,4 @@
+// Covers provider auth choice selection for plugin-owned providers.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createWizardPrompter } from "../../test/helpers/wizard-prompter.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/plugins/provider-config-context.types.ts b/src/plugins/provider-config-context.types.ts
@@ -1,3 +1,4 @@
+// Defines provider config context types for plugin-owned providers.
 import type { ModelProviderConfig } from "../config/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
diff --git a/src/plugins/provider-model-helpers.test.ts b/src/plugins/provider-model-helpers.test.ts
@@ -1,3 +1,4 @@
+// Covers provider model helper behavior for plugin model registries.
 import type { ModelRegistry } from "openclaw/plugin-sdk/agent-sessions";
 import { describe, expect, it } from "vitest";
 import { cloneFirstTemplateModel, matchesExactOrPrefix } from "./provider-model-helpers.js";
diff --git a/src/plugins/validation-diagnostics.ts b/src/plugins/validation-diagnostics.ts
@@ -1,3 +1,4 @@
+// Formats plugin validation diagnostics from manifest and config checks.
 import type { PluginDiagnostic } from "./manifest-types.js";
 
 /** Pushes a normalized plugin validation diagnostic. */
diff --git a/src/plugins/web-provider-public-artifacts.test.ts b/src/plugins/web-provider-public-artifacts.test.ts
@@ -1,3 +1,4 @@
+// Covers web provider public artifact extraction from plugin metadata.
 import { describe, expect, it } from "vitest";
 import { loadPluginManifestRegistry } from "./manifest-registry.js";
 import {
diff --git a/src/plugins/wired-hooks-after-tool-call.e2e.test.ts b/src/plugins/wired-hooks-after-tool-call.e2e.test.ts
@@ -1,3 +1,4 @@
+// Exercises wired plugin hooks after tool-call completion.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 /**
  * Test: after_tool_call hook wiring (embedded-agent-subscribe.handlers.tools.ts)

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Emits agent events requested by plugin hook contracts.`
`1`	`2`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`3`	`import { emitAgentEvent } from "../infra/agent-events.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Builds plugin API facades exposed to bundled and external plugins.`
`1`	`2`	`import type { OpenClawPluginApi } from "./types.js";`
`2`	`3`
`3`	`4`	`type PluginApiFacadeFields = Pick<`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies bundled plugin directory resolution.`
`1`	`2`	`import fs from "node:fs";`
`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`	`+// Converts ClawHub plugin entries into install records.`
`1`	`2`	`import type { PluginInstallRecord } from "../config/types.plugins.js";`
`2`	`3`	`import type { ClawHubPackageChannel, ClawHubPackageFamily } from "../infra/clawhub.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Resolves ClawHub plugin catalog entries and install metadata.`
`1`	`2`	`import { createHash } from "node:crypto";`
`2`	`3`	`import fs from "node:fs/promises";`
`3`	`4`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers plugin config policy validation and ownership decisions.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers copying bundled plugin metadata for package output.`
`1`	`2`	`import fs from "node:fs";`
`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`	`+// Verifies plugin hook security constraints and rejections.`
`1`	`2`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { createHookRunner } from "./hooks.js";`
`3`	`4`	`import { addStaticTestHooks } from "./hooks.test-helpers.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Parses host tool parameters supplied by plugin tool contracts.`
`1`	`2`	`import {`
`2`	`3`	`extractApplyPatchTargetPaths,`
`3`	`4`	`type ApplyPatchPathExtractionOptions,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers plugin install source info formatting and parsing.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { describePluginInstallSource } from "./install-source-info.js";`
`3`	`4`