docs: document plugin contract tests

src/plugins/contracts/auth-choice.contract.test.ts

@@ -1,3 +1,4 @@
+// Auth choice contract tests cover provider auth choice metadata and setup behavior.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearRuntimeAuthProfileStoreSnapshots } from "../../agents/auth-profiles/store.js";
 import { resolvePreferredProviderForAuthChoice } from "../../plugins/provider-auth-choice-preference.js";

src/plugins/contracts/boundary-invariants.test.ts

@@ -1,3 +1,4 @@
+// Boundary invariant tests cover plugin boundary rules that must hold across the repo.
 import { spawnSync } from "node:child_process";
 import fs, { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";

src/plugins/contracts/bundled-extension-config-api-guardrails.test.ts

@@ -1,3 +1,4 @@
+// Bundled extension config API guardrail tests cover config API usage in bundled extensions.
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/config-boundary-guard.test.ts

@@ -1,3 +1,4 @@
+// Config boundary guard tests cover plugin config ownership and forbidden core reads.
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";

src/plugins/contracts/config-footprint-guardrails.test.ts

@@ -1,3 +1,4 @@
+// Config footprint guardrail tests cover forbidden direct plugin config access patterns.
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/core-extension-facade-boundary.test.ts

@@ -1,3 +1,4 @@
+// Core extension facade boundary tests cover allowed imports between core and extension facades.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/deprecated-internal-config-api.test.ts

@@ -1,3 +1,4 @@
+// Deprecated internal config API tests cover forbidden legacy plugin config API usage.
 import { beforeAll, describe, expect, it } from "vitest";
 import { collectDeprecatedInternalConfigApiViolations } from "../../../scripts/lib/deprecated-config-api-guard.mjs";
 

src/plugins/contracts/embedding-provider.contract.test.ts

@@ -1,3 +1,4 @@
+// Embedding provider contract tests cover plugin embedding provider SDK behavior.
 import * as embeddingProviderSdk from "openclaw/plugin-sdk/embedding-providers";
 import {
   createPluginRegistryFixture,

src/plugins/contracts/extension-package-project-boundaries.test.ts

@@ -1,3 +1,4 @@
+// Extension package boundary tests cover package/project boundaries for bundled extensions.
 import fs from "node:fs";
 import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";

src/plugins/contracts/extension-runtime-dependencies.contract.test.ts

@@ -1,3 +1,4 @@
+// Extension runtime dependency contract tests cover runtime dependency placement for extensions.
 import fs from "node:fs";
 import { builtinModules } from "node:module";
 import path from "node:path";

src/plugins/contracts/host-hook-fixture.ts

@@ -1,3 +1,4 @@
+// Host hook fixtures provide reusable plugin host-hook doubles for contract tests.
 import type { OpenClawPluginApi } from "../types.js";
 
 export function registerHostHookFixture(api: OpenClawPluginApi) {

src/plugins/contracts/host-hooks.contract.test.ts

@@ -1,3 +1,4 @@
+// Host hook contract tests cover plugin host hook registration and runtime behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {

src/plugins/contracts/inventory/bundled-capability-metadata.ts

@@ -1,3 +1,4 @@
+// Bundled capability metadata inventory lists capability metadata used by plugin contracts.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/loader.contract.test.ts

@@ -1,3 +1,4 @@
+// Loader contract tests cover plugin loader behavior, registry setup, and reset boundaries.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { uniqueSortedStrings } from "../../plugin-sdk/test-helpers/string-utils.js";
 import { resolveManifestContractPluginIds } from "../plugin-registry.js";

src/plugins/contracts/memory-embedding-provider.contract.test.ts

@@ -1,3 +1,4 @@
+// Memory embedding provider contract tests cover memory plugin embedding provider behavior.
 import {
   createPluginRegistryFixture,
   registerVirtualTestPlugin,

src/plugins/contracts/model-catalog-core-imports.test.ts

@@ -1,3 +1,4 @@
+// Model catalog core import tests cover allowed model-catalog imports in plugin code.
 import fs from "node:fs";
 import path from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";

src/plugins/contracts/package-manifest.contract.test.ts

@@ -1,3 +1,4 @@
+// Package manifest contract tests cover plugin package manifest requirements.
 import { describePackageManifestContract } from "openclaw/plugin-sdk/plugin-test-contracts";
 
 type PackageManifestContractParams = Parameters<typeof describePackageManifestContract>[0];

src/plugins/contracts/plugin-entry-guardrails.test.ts

@@ -1,3 +1,4 @@
+// Plugin entry guardrail tests cover allowed plugin entrypoint imports and exports.
 import { existsSync, readFileSync } from "node:fs";
 import path, { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/plugin-registration.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin registration contract tests cover manifest registration cases exposed through the SDK.
 import { pluginRegistrationContractCases } from "openclaw/plugin-sdk/plugin-test-contracts";
 import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
 

src/plugins/contracts/plugin-sdk-index.bundle.test.ts

@@ -1,3 +1,4 @@
+// Plugin SDK bundle index tests cover bundled SDK export inventory and packaging.
 import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";

src/plugins/contracts/plugin-sdk-index.test.ts

@@ -1,3 +1,4 @@
+// Plugin SDK index tests cover SDK export baselines and public subpath availability.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts

@@ -1,3 +1,4 @@
+// Plugin SDK package guardrail tests cover package export and contract drift checks.
 import fs from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/plugin-sdk-root-alias.test.ts

@@ -1,3 +1,4 @@
+// Plugin SDK root alias tests cover package root alias compatibility for plugin authors.
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";

src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts

@@ -1,3 +1,4 @@
+// Plugin SDK runtime API guardrail tests cover runtime API export safety and boundaries.
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/plugin-sdk-subpaths.test.ts

@@ -1,3 +1,4 @@
+// Plugin SDK subpath tests cover documented SDK subpath exports and package aliases.
 import fs, { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

src/plugins/contracts/plugin-tool-contracts.test.ts

@@ -1,3 +1,4 @@
+// Plugin tool contract tests cover bundled plugin tool schemas and invocation contracts.
 import fs from "node:fs";
 import path from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";

src/plugins/contracts/provider-catalog-deprecation.contract.test.ts

@@ -1,3 +1,4 @@
+// Provider catalog deprecation contract tests cover deprecated provider catalog metadata.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";

src/plugins/contracts/provider-family-plugin-tests.test.ts

@@ -1,3 +1,4 @@
+// Provider family plugin tests cover grouped provider-family contract cases.
 import fs from "node:fs";
 import { basename, resolve } from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";

src/plugins/contracts/providers.contract.test.ts

@@ -1,3 +1,4 @@
+// Provider contract tests cover shared provider plugin behavior across bundled providers.
 import { describeProviderContracts } from "../../plugin-sdk/test-helpers/provider-contract.js";
 import { describeWebSearchProviderContracts } from "../../plugin-sdk/test-helpers/web-search-provider-contract.js";
 

src/plugins/contracts/registry.contract.test.ts

@@ -1,3 +1,4 @@
+// Registry contract tests cover plugin contract registry contents and lookup behavior.
 import { describe, expect, it } from "vitest";
 import { uniqueSortedStrings } from "../../plugin-sdk/test-helpers/string-utils.js";
 import { loadPluginManifestRegistry, type PluginManifestRecord } from "../manifest-registry.js";

src/plugins/contracts/registry.retry.test.ts

@@ -1,3 +1,4 @@
+// Registry retry tests cover plugin registry retry behavior after transient failures.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ProviderPlugin, WebFetchProviderPlugin, WebSearchProviderPlugin } from "../types.js";
 

src/plugins/contracts/registry.ts

@@ -1,3 +1,4 @@
+// Plugin contract registry assembles bundled plugin fixtures for shared contract tests.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { loadBundledCapabilityRuntimeRegistry } from "../bundled-capability-runtime.js";

src/plugins/contracts/run-context-lifecycle.contract.test.ts

@@ -1,3 +1,4 @@
+// Run context lifecycle contract tests cover plugin run context setup and cleanup.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {

src/plugins/contracts/runtime-import-side-effects.contract.test.ts

@@ -1,3 +1,4 @@
+// Runtime import side-effect contract tests cover cold import behavior for plugin runtime code.
 import fs from "node:fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { assertNoImportTimeSideEffects } from "../../plugin-sdk/test-helpers/import-side-effects.js";

src/plugins/contracts/runtime-seams.contract.test.ts

@@ -1,3 +1,4 @@
+// Runtime seam contract tests cover allowed plugin runtime entrypoints and import boundaries.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/plugins/contracts/scheduled-turns.contract.test.ts

@@ -1,3 +1,4 @@
+// Scheduled turn contract tests cover plugin scheduled turn metadata and timestamp bounds.
 import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion";
 import {
   createPluginRegistryFixture,

src/plugins/contracts/session-actions.contract.test.ts

@@ -1,3 +1,4 @@
+// Session action contract tests cover plugin session action metadata and execution contracts.
 import {
   createPluginRegistryFixture,
   registerTestPlugin,

src/plugins/contracts/session-attachments.contract.test.ts

@@ -1,3 +1,4 @@
+// Session attachment contract tests cover plugin session attachment metadata and storage.
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { FILE_TYPE_SNIFF_MAX_BYTES } from "@openclaw/media-core/mime";

src/plugins/contracts/session-entry-projection.contract.test.ts

@@ -1,3 +1,4 @@
+// Session entry projection contract tests cover plugin session entry projection behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {

src/plugins/contracts/shape.contract.test.ts

@@ -1,3 +1,4 @@
+// Plugin shape contract tests cover manifest, API, and runtime export shapes.
 import {
   createPluginRegistryFixture,
   registerVirtualTestPlugin,

src/plugins/contracts/speech-vitest-registry.ts

@@ -1,3 +1,4 @@
+// Speech Vitest registry helpers load speech capability runtimes for contract tests.
 import { loadBundledCapabilityRuntimeRegistry } from "../bundled-capability-runtime.js";
 import type {
   ImageGenerationProviderPlugin,

src/plugins/contracts/test-helpers/bundled-plugin-roots.ts

@@ -1,3 +1,4 @@
+// Bundled plugin root helpers resolve plugin root paths for contract test fixtures.
 import { relative, resolve } from "node:path";
 import { loadPluginManifestRegistry } from "../../manifest-registry.js";
 

src/plugins/contracts/tts-contract-suites.ts

@@ -1,3 +1,4 @@
+// TTS contract suites provide reusable text-to-speech plugin contract assertions.
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import {
   createEmptyPluginRegistry,

src/plugins/contracts/tts.contract.test.ts

@@ -1,3 +1,4 @@
+// TTS contract tests cover text-to-speech plugin capability and runtime behavior.
 import {
   describeTtsAutoApplyContract,
   describeTtsConfigContract,

src/plugins/contracts/web-fetch-provider.contract.test.ts

@@ -1,3 +1,4 @@
+// Web fetch provider contract tests cover plugin web-fetch provider behavior.
 import { describeWebFetchProviderContracts } from "../../plugin-sdk/test-helpers/web-fetch-provider-contract.js";
 import { pluginRegistrationContractRegistry } from "./registry.js";
 

src/plugins/contracts/wizard.choice-resolution.contract.test.ts

@@ -1,3 +1,4 @@
+// Wizard choice resolution contract tests cover provider setup choice matching.
 import { describeProviderWizardChoiceResolutionContract } from "openclaw/plugin-sdk/provider-test-contracts";
 
 describeProviderWizardChoiceResolutionContract();

src/plugins/contracts/wizard.model-picker.contract.test.ts

@@ -1,3 +1,4 @@
+// Wizard model picker contract tests cover provider setup wizard model selection.
 import { describeProviderWizardModelPickerContract } from "openclaw/plugin-sdk/provider-test-contracts";
 
 describeProviderWizardModelPickerContract();

src/plugins/contracts/wizard.setup-options.contract.test.ts

@@ -1,3 +1,4 @@
+// Wizard setup option contract tests cover provider setup option metadata.
 import { describeProviderWizardSetupOptionsContract } from "openclaw/plugin-sdk/provider-test-contracts";
 
 describeProviderWizardSetupOptionsContract();