docs: document smoke test scripts

scripts/sqlite-vec-smoke.mjs

@@ -1,3 +1,5 @@
+// Verifies sqlite-vec can load and execute a simple vector query in Node's
+// built-in SQLite runtime.
 import { DatabaseSync } from "node:sqlite";
 import { load, getLoadablePath } from "sqlite-vec";
 import { formatErrorMessage } from "./lib/error-format.mjs";

scripts/stage-bundled-plugin-runtime.mjs

@@ -1,3 +1,5 @@
+// Stages bundled plugin runtime overlays into dist-runtime with SDK aliases and
+// Windows-safe symlink fallbacks.
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -319,6 +321,9 @@ function stagePluginRuntimeOverlay(sourceDir, targetDir, relativeDir = "") {
   }
 }
 
+/**
+ * Stages runtime plugin entries and aliases used by packaged bundled plugins.
+ */
 export function stageBundledPluginRuntime(params = {}) {
   const repoRoot = params.cwd ?? params.repoRoot ?? process.cwd();
   const distRoot = path.join(repoRoot, "dist");

scripts/sync-openclaw-label-colors.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Synchronizes GitHub label colors to the OpenClaw taxonomy policy.
 import { execFileSync } from "node:child_process";
 
 const REPO = "openclaw/openclaw";

scripts/sync-plugin-sdk-exports.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// Regenerates package.json plugin-sdk export entries from the canonical entry list.
 import fs from "node:fs";
 import path from "node:path";
 import { buildPluginSdkPackageExports } from "./lib/plugin-sdk-entries.mjs";

scripts/test-built-bundled-channel-entry-smoke.mjs

@@ -1,3 +1,5 @@
+// Smoke-tests packaged bundled channel entrypoints in source and installed
+// package layouts.
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";

scripts/test-built-plugin-singleton.mjs

@@ -1,3 +1,4 @@
+// Smoke-tests the built plugin loader singleton and bundled plugin runtime overlay.
 import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";

scripts/test-built-status-message-runtime.mjs

@@ -1,3 +1,4 @@
+// Smoke-tests that the built status-message runtime bundle is discoverable and loadable.
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -7,16 +8,18 @@ import { parsePackageRootArg } from "./lib/package-root-args.mjs";
 
 const STATUS_MESSAGE_RUNTIME_RE = /^status-message\.runtime(?:-[A-Za-z0-9_-]+)?\.js$/u;
 
+/**
+ * Finds the preferred built status-message runtime bundle under dist.
+ */
 export function findBuiltStatusMessageRuntimePath(distDir) {
-  const candidates = listBuiltStatusMessageRuntimeFiles(distDir)
-    .toSorted((left, right) => {
-      const leftHasHash = left !== "status-message.runtime.js";
-      const rightHasHash = right !== "status-message.runtime.js";
-      if (leftHasHash !== rightHasHash) {
-        return leftHasHash ? -1 : 1;
-      }
-      return left.localeCompare(right);
-    });
+  const candidates = listBuiltStatusMessageRuntimeFiles(distDir).toSorted((left, right) => {
+    const leftHasHash = left !== "status-message.runtime.js";
+    const rightHasHash = right !== "status-message.runtime.js";
+    if (leftHasHash !== rightHasHash) {
+      return leftHasHash ? -1 : 1;
+    }
+    return left.localeCompare(right);
+  });
 
   assert.ok(candidates.length > 0, `missing built status-message runtime bundle under ${distDir}`);
 

scripts/test-cli-startup-bench-budget.mjs

@@ -1,3 +1,4 @@
+// Compares CLI startup benchmark reports against checked-in budgets.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { booleanFlag, intFlag, parseFlagArgs, stringFlag } from "./lib/arg-utils.mjs";

scripts/test-extension-batch.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// Runs grouped Vitest plans for one or more bundled plugins.
 import path from "node:path";
 import {
   listTrackedTestFilesForRoots,
@@ -22,6 +23,9 @@ function printUsage() {
   );
 }
 
+/**
+ * Parses comma-separated plugin ids and separates Vitest passthrough args.
+ */
 export function parseExtensionIds(rawArgs) {
   const normalizedArgs = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
   const separatorIndex = normalizedArgs.indexOf("--");
@@ -46,6 +50,9 @@ export function parseExtensionIds(rawArgs) {
   };
 }
 
+/**
+ * Resolves bounded parallelism for extension test config groups.
+ */
 export function resolveExtensionBatchParallelism(groupCount, env = process.env) {
   const raw = env[PARALLEL_ENV_KEY]?.trim();
   const override = raw ? parsePositiveInt(raw, PARALLEL_ENV_KEY) : 1;
@@ -104,6 +111,9 @@ function isExactExcludePath(inputPath) {
   return !/[*!?[\]{}]/u.test(inputPath);
 }
 
+/**
+ * Collects exact --exclude paths so empty groups can be reported accurately.
+ */
 export function parseExactVitestExcludePaths(vitestArgs) {
   const excludePaths = new Set();
   for (let index = 0; index < vitestArgs.length; index += 1) {
@@ -163,6 +173,9 @@ async function runPlanGroup(group, params) {
   });
 }
 
+/**
+ * Runs a resolved extension batch plan, optionally in parallel config groups.
+ */
 export async function runExtensionBatchPlan(batchPlan, params = {}) {
   const env = params.env ?? process.env;
   const vitestArgs = params.vitestArgs ?? [];

scripts/test-extension.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// Runs the Vitest plan for one bundled plugin by id or path.
 import { formatErrorMessage } from "./lib/error-format.mjs";
 import { resolveExtensionTestPlan } from "./lib/extension-test-plan.mjs";
 import { isDirectScriptRun, runVitestBatch } from "./lib/vitest-batch-runner.mjs";