refactor(qa): split Matrix QA into optional plugin (#66723)

Merged via squash.

Prepared head SHA: 27241bd089
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

scripts/build-all.mjs

@@ -10,11 +10,6 @@ export const BUILD_ALL_STEPS = [
   { label: "canvas:a2ui:bundle", kind: "pnpm", pnpmArgs: ["canvas:a2ui:bundle"] },
   { label: "tsdown", kind: "node", args: ["scripts/tsdown-build.mjs"] },
   { label: "runtime-postbuild", kind: "node", args: ["scripts/runtime-postbuild.mjs"] },
-  {
-    label: "write-npm-update-compat-sidecars",
-    kind: "node",
-    args: ["scripts/write-npm-update-compat-sidecars.mjs"],
-  },
   { label: "build-stamp", kind: "node", args: ["scripts/build-stamp.mjs"] },
   {
     label: "build:plugin-sdk:dts",

scripts/generate-qa-runner-catalog.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { writeBundledQaRunnerCatalog } from "../src/plugins/qa-runner-catalog.js";
+
+const args = new Set(process.argv.slice(2));
+const checkOnly = args.has("--check");
+const writeMode = args.has("--write");
+
+if (checkOnly === writeMode) {
+  console.error("Use exactly one of --check or --write.");
+  process.exit(1);
+}
+
+const repoRoot = process.cwd();
+const result = await writeBundledQaRunnerCatalog({
+  repoRoot,
+  check: checkOnly,
+});
+
+if (checkOnly) {
+  if (result.changed) {
+    console.error(
+      [
+        "QA runner catalog drift detected.",
+        `Expected current: ${path.relative(repoRoot, result.jsonPath)}`,
+        "If this QA runner metadata change is intentional, run `pnpm qa-runners:gen` and commit the updated baseline file.",
+        "If not intentional, fix the bundled plugin metadata drift first.",
+      ].join("\n"),
+    );
+    process.exit(1);
+  }
+  console.log(`OK ${path.relative(repoRoot, result.jsonPath)}`);
+} else {
+  console.log(`Wrote ${path.relative(repoRoot, result.jsonPath)}`);
+}

scripts/lib/bundled-plugin-build-entries.mjs

@@ -8,7 +8,7 @@ import {
 import { shouldBuildBundledCluster } from "./optional-bundled-clusters.mjs";
 
 const TOP_LEVEL_PUBLIC_SURFACE_EXTENSIONS = new Set([".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"]);
-const NON_PACKAGED_BUNDLED_PLUGIN_DIRS = new Set(["qa-channel", "qa-lab"]);
+const NON_PACKAGED_BUNDLED_PLUGIN_DIRS = new Set(["qa-channel", "qa-lab", "qa-matrix"]);
 const toPosixPath = (value) => value.replaceAll("\\", "/");
 
 function readBundledPluginPackageJson(packageJsonPath) {

scripts/lib/npm-update-compat-sidecars.mjs

@@ -1,16 +0,0 @@
-export const NPM_UPDATE_COMPAT_SIDECARS = [
-  {
-    path: "dist/extensions/qa-channel/runtime-api.js",
-    content:
-      "// Compatibility stub for older OpenClaw updaters. The QA channel implementation is not packaged.\nexport {};\n",
-  },
-  {
-    path: "dist/extensions/qa-lab/runtime-api.js",
-    content:
-      "// Compatibility stub for older OpenClaw updaters. The QA lab implementation is not packaged.\nexport {};\n",
-  },
-];
-
-export const NPM_UPDATE_COMPAT_SIDECAR_PATHS = new Set(
-  NPM_UPDATE_COMPAT_SIDECARS.map((entry) => entry.path),
-);

scripts/lib/plugin-sdk-entrypoints.json

@@ -179,6 +179,8 @@
   "matrix-runtime-surface",
   "matrix-surface",
   "matrix-thread-bindings",
+  "qa-lab-runtime",
+  "qa-runner-runtime",
   "mattermost",
   "mattermost-policy",
   "memory-core",

scripts/lib/qa-runner-catalog.json

@@ -0,0 +1,8 @@
+[
+  {
+    "pluginId": "qa-matrix",
+    "commandName": "matrix",
+    "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver",
+    "npmSpec": "@openclaw/qa-matrix"
+  }
+]

scripts/openclaw-npm-postpublish-verify.ts

@@ -20,7 +20,6 @@ import {
   collectRootDistBundledRuntimeMirrors,
   collectRuntimeDependencySpecs,
 } from "./lib/bundled-plugin-root-runtime-mirrors.mjs";
-import { NPM_UPDATE_COMPAT_SIDECAR_PATHS } from "./lib/npm-update-compat-sidecars.mjs";
 import { runInstalledWorkspaceBootstrapSmoke } from "./lib/workspace-bootstrap-smoke.mjs";
 import { parseReleaseVersion, resolveNpmCommandInvocation } from "./openclaw-npm-release-check.ts";
 
@@ -44,13 +43,6 @@ type InstalledBundledExtensionManifestRecord = {
 const MAX_BUNDLED_EXTENSION_MANIFEST_BYTES = 1024 * 1024;
 const LEGACY_CONTEXT_ENGINE_UNRESOLVED_RUNTIME_MARKER =
   "Failed to load legacy context engine runtime.";
-const NPM_UPDATE_COMPAT_EXTENSION_DIRS = new Set(
-  [...NPM_UPDATE_COMPAT_SIDECAR_PATHS].map((relativePath) => {
-    const pathParts = relativePath.split("/");
-    pathParts.pop();
-    return pathParts.join("/");
-  }),
-);
 
 export type PublishedInstallScenario = {
   name: string;
@@ -183,20 +175,6 @@ function collectExpectedBundledExtensionPackageIds(
   return ids;
 }
 
-function isNpmUpdateCompatOnlyExtensionDir(params: {
-  extensionId: string;
-  packageRoot: string;
-}): boolean {
-  const relativeExtensionDir = `dist/extensions/${params.extensionId}`;
-  if (!NPM_UPDATE_COMPAT_EXTENSION_DIRS.has(relativeExtensionDir)) {
-    return false;
-  }
-
-  return [...NPM_UPDATE_COMPAT_SIDECAR_PATHS]
-    .filter((relativePath) => relativePath.startsWith(`${relativeExtensionDir}/`))
-    .every((relativePath) => existsSync(join(params.packageRoot, relativePath)));
-}
-
 function readBundledExtensionPackageJsons(packageRoot: string): {
   manifests: InstalledBundledExtensionManifestRecord[];
   errors: string[];
@@ -218,9 +196,6 @@ function readBundledExtensionPackageJsons(packageRoot: string): {
     const extensionDirPath = join(extensionsDir, entry.name);
     const packageJsonPath = join(extensionsDir, entry.name, "package.json");
     if (!existsSync(packageJsonPath)) {
-      if (isNpmUpdateCompatOnlyExtensionDir({ extensionId: entry.name, packageRoot })) {
-        continue;
-      }
       if (expectedPackageIds === null || expectedPackageIds.has(entry.name)) {
         errors.push(`installed bundled extension manifest missing: ${packageJsonPath}.`);
       }

scripts/openclaw-npm-release-check.ts

@@ -9,7 +9,6 @@ import {
   resolveNpmDistTagMirrorAuth as resolveNpmDistTagMirrorAuthBase,
   parseReleaseVersion as parseReleaseVersionBase,
 } from "./lib/npm-publish-plan.mjs";
-import { NPM_UPDATE_COMPAT_SIDECAR_PATHS } from "./lib/npm-update-compat-sidecars.mjs";
 import { WORKSPACE_TEMPLATE_PACK_PATHS } from "./lib/workspace-bootstrap-smoke.mjs";
 
 type PackageJson = {
@@ -465,9 +464,6 @@ function collectPackedTarballErrors(): string[] {
 export function collectForbiddenPackedPathErrors(paths: Iterable<string>): string[] {
   const errors: string[] = [];
   for (const packedPath of paths) {
-    if (NPM_UPDATE_COMPAT_SIDECAR_PATHS.has(packedPath)) {
-      continue;
-    }
     const matchedRule = FORBIDDEN_PACKED_PATH_RULES.find((rule) =>
       packedPath.startsWith(rule.prefix),
     );

scripts/write-npm-update-compat-sidecars.mjs

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs";
-import path from "node:path";
-import { NPM_UPDATE_COMPAT_SIDECARS } from "./lib/npm-update-compat-sidecars.mjs";
-
-for (const entry of NPM_UPDATE_COMPAT_SIDECARS) {
-  fs.mkdirSync(path.dirname(entry.path), { recursive: true });
-  fs.writeFileSync(entry.path, entry.content, "utf8");
-}