Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

packages/plugin-package-contract/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@openclaw/plugin-package-contract",
+  "version": "0.0.0-private",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

packages/plugin-package-contract/src/index.test.ts

@@ -0,0 +1,84 @@
+// Plugin Package Contract tests cover index behavior.
+import { describe, expect, it } from "vitest";
+import {
+  EXTERNAL_CODE_PLUGIN_REQUIRED_FIELD_PATHS,
+  listMissingExternalCodePluginFieldPaths,
+  normalizeExternalPluginCompatibility,
+  validateExternalCodePluginPackageJson,
+} from "./index.js";
+
+describe("@openclaw/plugin-package-contract", () => {
+  it("normalizes the OpenClaw compatibility block for external plugins", () => {
+    expect(
+      normalizeExternalPluginCompatibility({
+        version: "1.2.3",
+        openclaw: {
+          compat: {
+            pluginApi: ">=2026.3.24-beta.2",
+            minGatewayVersion: "2026.3.24-beta.2",
+          },
+          build: {
+            openclawVersion: "2026.3.24-beta.2",
+            pluginSdkVersion: "0.9.0",
+          },
+        },
+      }),
+    ).toEqual({
+      pluginApiRange: ">=2026.3.24-beta.2",
+      builtWithOpenClawVersion: "2026.3.24-beta.2",
+      pluginSdkVersion: "0.9.0",
+      minGatewayVersion: "2026.3.24-beta.2",
+    });
+  });
+
+  it("falls back to install.minHostVersion and package version when compatible", () => {
+    expect(
+      normalizeExternalPluginCompatibility({
+        version: "1.2.3",
+        openclaw: {
+          compat: {
+            pluginApi: ">=1.0.0",
+          },
+          install: {
+            minHostVersion: "2026.3.24-beta.2",
+          },
+        },
+      }),
+    ).toEqual({
+      pluginApiRange: ">=1.0.0",
+      builtWithOpenClawVersion: "1.2.3",
+      minGatewayVersion: "2026.3.24-beta.2",
+    });
+  });
+
+  it("lists the required external code-plugin fields", () => {
+    expect(EXTERNAL_CODE_PLUGIN_REQUIRED_FIELD_PATHS).toEqual([
+      "openclaw.compat.pluginApi",
+      "openclaw.build.openclawVersion",
+    ]);
+  });
+
+  it("reports missing required fields with stable field paths", () => {
+    const packageJson = {
+      openclaw: {
+        compat: {},
+        build: {},
+      },
+    };
+
+    expect(listMissingExternalCodePluginFieldPaths(packageJson)).toEqual([
+      "openclaw.compat.pluginApi",
+      "openclaw.build.openclawVersion",
+    ]);
+    expect(validateExternalCodePluginPackageJson(packageJson).issues).toEqual([
+      {
+        fieldPath: "openclaw.compat.pluginApi",
+        message: "openclaw.compat.pluginApi is required for external code plugin packages.",
+      },
+      {
+        fieldPath: "openclaw.build.openclawVersion",
+        message: "openclaw.build.openclawVersion is required for external code plugin packages.",
+      },
+    ]);
+  });
+});

packages/plugin-package-contract/src/index.ts

@@ -0,0 +1,113 @@
+// External code plugin package.json compatibility and validation contracts.
+
+/** JSON object shape accepted by package contract helpers. */
+export type JsonObject = Record<string, unknown>;
+
+/** Compatibility metadata extracted from an external plugin package. */
+export type ExternalPluginCompatibility = {
+  pluginApiRange?: string;
+  builtWithOpenClawVersion?: string;
+  pluginSdkVersion?: string;
+  minGatewayVersion?: string;
+};
+
+/** One validation issue for an external plugin package. */
+export type ExternalPluginValidationIssue = {
+  fieldPath: string;
+  message: string;
+};
+
+/** Validation result plus any normalized compatibility metadata. */
+export type ExternalCodePluginValidationResult = {
+  compatibility?: ExternalPluginCompatibility;
+  issues: ExternalPluginValidationIssue[];
+};
+
+/** Required package.json field paths for external code plugin packages. */
+export const EXTERNAL_CODE_PLUGIN_REQUIRED_FIELD_PATHS = [
+  "openclaw.compat.pluginApi",
+  "openclaw.build.openclawVersion",
+] as const;
+
+/** Narrow unknown values to plain records. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Normalize optional package metadata strings. */
+function normalizeOptionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/** Read OpenClaw package.json blocks without trusting caller input shape. */
+function readOpenClawBlock(packageJson: unknown) {
+  const root = isRecord(packageJson) ? packageJson : undefined;
+  const openclaw = isRecord(root?.openclaw) ? root.openclaw : undefined;
+  const compat = isRecord(openclaw?.compat) ? openclaw.compat : undefined;
+  const build = isRecord(openclaw?.build) ? openclaw.build : undefined;
+  const install = isRecord(openclaw?.install) ? openclaw.install : undefined;
+  return { root, openclaw, compat, build, install };
+}
+
+/** Normalize compatibility metadata from an external plugin package.json. */
+export function normalizeExternalPluginCompatibility(
+  packageJson: unknown,
+): ExternalPluginCompatibility | undefined {
+  const { root, compat, build, install } = readOpenClawBlock(packageJson);
+  const version = normalizeOptionalString(root?.version);
+  const minHostVersion = normalizeOptionalString(install?.minHostVersion);
+  const compatibility: ExternalPluginCompatibility = {};
+
+  const pluginApi = normalizeOptionalString(compat?.pluginApi);
+  if (pluginApi) {
+    compatibility.pluginApiRange = pluginApi;
+  }
+
+  const minGatewayVersion = normalizeOptionalString(compat?.minGatewayVersion) ?? minHostVersion;
+  if (minGatewayVersion) {
+    compatibility.minGatewayVersion = minGatewayVersion;
+  }
+
+  const builtWithOpenClawVersion = normalizeOptionalString(build?.openclawVersion) ?? version;
+  if (builtWithOpenClawVersion) {
+    compatibility.builtWithOpenClawVersion = builtWithOpenClawVersion;
+  }
+
+  const pluginSdkVersion = normalizeOptionalString(build?.pluginSdkVersion);
+  if (pluginSdkVersion) {
+    compatibility.pluginSdkVersion = pluginSdkVersion;
+  }
+
+  return Object.keys(compatibility).length > 0 ? compatibility : undefined;
+}
+
+/** List missing required field paths for an external code plugin package.json. */
+export function listMissingExternalCodePluginFieldPaths(packageJson: unknown): string[] {
+  const { compat, build } = readOpenClawBlock(packageJson);
+  const missing: string[] = [];
+  if (!normalizeOptionalString(compat?.pluginApi)) {
+    missing.push("openclaw.compat.pluginApi");
+  }
+  if (!normalizeOptionalString(build?.openclawVersion)) {
+    missing.push("openclaw.build.openclawVersion");
+  }
+  return missing;
+}
+
+/** Validate an external code plugin package.json against required compatibility fields. */
+export function validateExternalCodePluginPackageJson(
+  packageJson: unknown,
+): ExternalCodePluginValidationResult {
+  const issues = listMissingExternalCodePluginFieldPaths(packageJson).map((fieldPath) => ({
+    fieldPath,
+    message: `${fieldPath} is required for external code plugin packages.`,
+  }));
+  return {
+    compatibility: normalizeExternalPluginCompatibility(packageJson),
+    issues,
+  };
+}