[codex] harden clawhub plugin publishing and install (#56870)

* fix: harden clawhub plugin publishing and install

* fix(process): preserve windows shim exit success

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

@@ -0,0 +1,85 @@
+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 plugins published to ClawHub.",
+      },
+      {
+        fieldPath: "openclaw.build.openclawVersion",
+        message:
+          "openclaw.build.openclawVersion is required for external code plugins published to ClawHub.",
+      },
+    ]);
+  });
+});

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

@@ -0,0 +1,96 @@
+export type JsonObject = Record<string, unknown>;
+
+export type ExternalPluginCompatibility = {
+  pluginApiRange?: string;
+  builtWithOpenClawVersion?: string;
+  pluginSdkVersion?: string;
+  minGatewayVersion?: string;
+};
+
+export type ExternalPluginValidationIssue = {
+  fieldPath: string;
+  message: string;
+};
+
+export type ExternalCodePluginValidationResult = {
+  compatibility?: ExternalPluginCompatibility;
+  issues: ExternalPluginValidationIssue[];
+};
+
+export const EXTERNAL_CODE_PLUGIN_REQUIRED_FIELD_PATHS = [
+  "openclaw.compat.pluginApi",
+  "openclaw.build.openclawVersion",
+] as const;
+
+function isRecord(value: unknown): value is JsonObject {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function getTrimmedString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+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 };
+}
+
+export function normalizeExternalPluginCompatibility(
+  packageJson: unknown,
+): ExternalPluginCompatibility | undefined {
+  const { root, compat, build, install } = readOpenClawBlock(packageJson);
+  const version = getTrimmedString(root?.version);
+  const minHostVersion = getTrimmedString(install?.minHostVersion);
+  const compatibility: ExternalPluginCompatibility = {};
+
+  const pluginApi = getTrimmedString(compat?.pluginApi);
+  if (pluginApi) {
+    compatibility.pluginApiRange = pluginApi;
+  }
+
+  const minGatewayVersion = getTrimmedString(compat?.minGatewayVersion) ?? minHostVersion;
+  if (minGatewayVersion) {
+    compatibility.minGatewayVersion = minGatewayVersion;
+  }
+
+  const builtWithOpenClawVersion = getTrimmedString(build?.openclawVersion) ?? version;
+  if (builtWithOpenClawVersion) {
+    compatibility.builtWithOpenClawVersion = builtWithOpenClawVersion;
+  }
+
+  const pluginSdkVersion = getTrimmedString(build?.pluginSdkVersion);
+  if (pluginSdkVersion) {
+    compatibility.pluginSdkVersion = pluginSdkVersion;
+  }
+
+  return Object.keys(compatibility).length > 0 ? compatibility : undefined;
+}
+
+export function listMissingExternalCodePluginFieldPaths(packageJson: unknown): string[] {
+  const { compat, build } = readOpenClawBlock(packageJson);
+  const missing: string[] = [];
+  if (!getTrimmedString(compat?.pluginApi)) {
+    missing.push("openclaw.compat.pluginApi");
+  }
+  if (!getTrimmedString(build?.openclawVersion)) {
+    missing.push("openclaw.build.openclawVersion");
+  }
+  return missing;
+}
+
+export function validateExternalCodePluginPackageJson(
+  packageJson: unknown,
+): ExternalCodePluginValidationResult {
+  const issues = listMissingExternalCodePluginFieldPaths(packageJson).map((fieldPath) => ({
+    fieldPath,
+    message: `${fieldPath} is required for external code plugins published to ClawHub.`,
+  }));
+  return {
+    compatibility: normalizeExternalPluginCompatibility(packageJson),
+    issues,
+  };
+}