@openclaw/plugin-inspector 0.3.18 → 0.3.20

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.20 - 2026-07-31
+
+### Added
+
+- Resolve `latest`, `beta`, or exact OpenClaw npm versions for compatibility inspection, reuse prepared targets from cache, and report exact target/source metadata.
+
+### Fixed
+
+- Treat version-derived API removals inside a plugin's declared OpenClaw range as author-facing errors while keeping out-of-range targets informational, including beta eligibility against the upcoming stable version.
+- Accept tested minimum OpenClaw host versions below a plugin's build version without reporting package metadata drift.
+- Ignore type-only OpenClaw SDK imports when classifying runtime compatibility against a target release.
+- Accept `openclaw.runtimeSetupEntry` and other paired compiled runtime entrypoints as valid replacements for absent source entrypoints.
+
+## 0.3.19 - 2026-07-27
+
+### Highlights
+
+- Restore silently-lost manifest contract findings after OpenClaw moved its public manifest types into `manifest-types.ts`.
+
+### Changed
+
+- Refresh generated and repository GitHub Actions workflows to the current checkout, setup-node, upload-artifact, and pnpm/action-setup releases.
+
 ## 0.3.18 - 2026-07-21
 
 ### Highlights

package/README.md

@@ -34,6 +34,12 @@ checkout. If an OpenClaw checkout is supplied with `--openclaw <path>`, the
 inspector only reads public compatibility surfaces such as compat records, SDK
 exports, hook names, manifest fields, and registrar metadata.
 
+Pass `--openclaw-version latest`, `--openclaw-version beta`, or an exact
+published version to resolve an official OpenClaw npm target. Reports keep the
+exact resolved version and npm source metadata. Prepared targets are cached, so
+batch and repeated inspections do not download the same OpenClaw package for
+each plugin.
+
 ## Quick Start
 
 Run this from a plugin package root:
@@ -181,6 +187,7 @@ Common options:
 | `--config <path>` | Read a standalone config file. Required for fixture-suite `report`. |
 | `--out <dir>` | Write reports somewhere other than `reports/`. |
 | `--openclaw <path>` | Compare against a local OpenClaw checkout. |
+| `--openclaw-version latest\|beta\|<exact>` | Resolve and compare against an official OpenClaw npm release. |
 | `--no-openclaw` | Disable OpenClaw checkout comparison. |
 | `--runtime` / `--capture` | Add opt-in runtime registration capture. |
 | `--no-runtime` / `--no-capture` | Disable runtime capture even when config enables it. |
@@ -256,14 +263,14 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
           cache: npm
       - run: npm ci
       - run: npx @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: plugin-inspector-reports
@@ -298,7 +305,7 @@ Important report sections:
 | --- | --- |
 | `status` | `pass` unless hard breakages exist. |
 | `summary` | Counts for fixtures, breakages, warnings, suggestions, issues, issue classes, and contract probes. |
-| `targetOpenClaw` | Status and public compatibility data read from the optional OpenClaw checkout. |
+| `targetOpenClaw` | Exact resolved version, source metadata, cache state, and public compatibility data for the selected OpenClaw target. |
 | `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, SDK imports, and SDK deprecation evidence. |
 | `breakages` | Blocking compatibility failures. |
 | `warnings` / `suggestions` | Non-blocking compatibility findings. |
@@ -309,8 +316,9 @@ Important report sections:
 
 Default `check`, `ci`, and `batch` reports include both author-facing and
 internal findings. Pass `--author-facing` when producing plugin-author output;
-that filtered view includes only findings with `authorRemediation.summary` and
-`authorRemediation.docsUrl`.
+that filtered view includes only findings with `authorRemediation.summary`.
+Curated fixes include `authorRemediation.docsUrl`; dynamically discovered API
+removals use generic remediation without inventing a documentation URL.
 Current author-facing deprecation warnings include deprecated SDK helpers such
 as `loadSessionStore(...)` when a plugin still depends on the legacy whole-store
 session shape.

package/examples/github-actions-code-scanning.yml

@@ -13,8 +13,8 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
           cache: npm
@@ -24,7 +24,7 @@ jobs:
         if: always()
         with:
           sarif_file: reports/plugin-inspector.sarif
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: plugin-inspector-reports

package/examples/github-actions-plugin-inspector.yml

@@ -9,14 +9,14 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
           cache: npm
       - run: npm ci
       - run: npx @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: plugin-inspector-reports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",
@@ -31,6 +31,7 @@
     "./execution-results": "./src/execution-results.js",
     "./import-loop-profile": "./src/import-loop-profile.js",
     "./openclaw-target": "./src/openclaw-target.js",
+    "./openclaw-version": "./src/openclaw-version.js",
     "./platform-probes": "./src/platform-probes.js",
     "./profile-diff": "./src/profile-diff.js",
     "./ref-diff": "./src/ref-diff.js",
@@ -69,5 +70,9 @@
     "plugin",
     "compatibility",
     "ci"
-  ]
+  ],
+  "dependencies": {
+    "semver": "^7.8.5",
+    "tar": "^7.5.22"
+  }
 }

package/src/advanced.js

@@ -116,6 +116,13 @@ export {
   parseTypeFields,
   readOpenClawTargetSurface,
 } from "./openclaw-target.js";
+export {
+  openClawEligibilityVersion,
+  prepareOpenClawTarget,
+  resolveOpenClawTargetVersion,
+  satisfiesOpenClawCompatibilityRange,
+  satisfiesOpenClawVersionRange,
+} from "./openclaw-version.js";
 export {
   captureEntrypoint,
   captureEntrypointWithMockSdk,

package/src/api.js

@@ -46,6 +46,7 @@ export async function inspectPluginRoot(options = {}) {
     authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     openclawPath: options.openclawPath,
+    openclawVersion: options.openclawVersion,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
   });
@@ -62,6 +63,7 @@ export async function inspectCompatibilityFixtureSetConfig(options = {}) {
     authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     openclawPath: options.openclawPath,
+    openclawVersion: options.openclawVersion,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
   });
@@ -117,6 +119,7 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
       authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
       openclawPath: options.openclawPath,
+      openclawVersion: options.openclawVersion,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
     }));
@@ -150,6 +153,7 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
       authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
       openclawPath: options.openclawPath,
+      openclawVersion: options.openclawVersion,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
     }));

package/src/batch.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { renderMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
 import { runPluginCheck } from "./api.js";
+import { prepareOpenClawTarget, resolveOpenClawTargetVersion } from "./openclaw-version.js";
 
 const ignoredDirs = new Set([
   ".git",
@@ -22,6 +23,11 @@ export async function runBatchAnalysis(options = {}) {
   const outRoot = path.resolve(rootDir, outDir);
   const concurrency = Math.max(1, Math.min(Math.round(options.concurrency ?? 4), 32));
   const keepPluginReports = options.keepPluginReports === true;
+  const targetOpenClaw =
+    options.targetOpenClaw ??
+    (options.openclawVersion
+      ? await prepareOpenClawTarget(await resolveOpenClawTargetVersion(options.openclawVersion, options), options)
+      : undefined);
   const pluginRoots = await discoverPluginRoots(rootDir);
   const tempRoot = keepPluginReports ? null : await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-batch-"));
   const entries = [];
@@ -37,6 +43,7 @@ export async function runBatchAnalysis(options = {}) {
           rootDir,
           outDir: reportsRoot,
           openclawPath: options.openclawPath,
+          targetOpenClaw,
         }),
       );
     });
@@ -113,6 +120,7 @@ async function inspectBatchPlugin(pluginRoot, options) {
       configPath: options.configPath,
       mockSdk: options.mockSdk,
       openclawPath: options.openclawPath,
+      targetOpenClaw: options.targetOpenClaw,
       outDir: options.outDir,
       pluginRoot,
     });

package/src/cli.js

@@ -57,9 +57,10 @@ try {
 }
 
 async function runBatch(commandArgs) {
-  const inputDir = readFirstPositional(commandArgs, new Set(["--out", "--openclaw", "--concurrency"]));
+  const inputDir = readFirstPositional(commandArgs, new Set(["--out", "--openclaw", "--openclaw-version", "--concurrency"]));
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const concurrency = Number(readFlag(commandArgs, "--concurrency") ?? "4");
   const json = commandArgs.includes("--json");
   const check = commandArgs.includes("--check");
@@ -72,6 +73,7 @@ async function runBatch(commandArgs) {
     rootDir: inputDir,
     outDir,
     openclawPath,
+    openclawVersion,
     concurrency,
     authorFacing,
     keepPluginReports,
@@ -105,6 +107,7 @@ async function runCheck(commandArgs, options = {}) {
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const json = commandArgs.includes("--json");
   const capture = readRuntimeFlag(commandArgs);
   const mockSdk = readMockSdkFlag(commandArgs);
@@ -118,6 +121,7 @@ async function runCheck(commandArgs, options = {}) {
     configPath,
     mockSdk,
     openclawPath,
+    openclawVersion,
     outDir,
     pluginRoot,
   });
@@ -169,15 +173,17 @@ async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
   const ciOutputs = readCiOutputFlags(commandArgs);
   const authorFacing = readAuthorFacingFlag(commandArgs);
   const config = await loadInspectorConfig(configPath);
-  const report = authorFacing
-    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath })
+  const compatibilityInspection = authorFacing || typeof openclawPath === "string" || openclawVersion !== null;
+  const report = compatibilityInspection
+    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath, openclawVersion })
     : await inspectFixtureSet(config);
-  const paths = authorFacing
+  const paths = compatibilityInspection
     ? await writeCompatibilityReport(report, { cwd: config.rootDir, outDir })
     : await writeReport(report, { outDir });
   await writeCiOutputArtifacts(report, {
@@ -202,6 +208,7 @@ async function runCi(commandArgs) {
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const openclawVersion = readOpenClawVersion(commandArgs);
   const json = commandArgs.includes("--json");
   const capture = readRuntimeFlag(commandArgs);
   const mockSdk = readMockSdkFlag(commandArgs);
@@ -215,6 +222,7 @@ async function runCi(commandArgs) {
     configPath,
     mockSdk,
     openclawPath,
+    openclawVersion,
     outDir,
     pluginRoot,
   });
@@ -256,12 +264,13 @@ async function runCiCompatibilityReport({
   configPath,
   mockSdk,
   openclawPath,
+  openclawVersion,
   outDir,
   pluginRoot,
 }) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
-    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath });
+    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath, openclawVersion });
     await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
     return {
       report,
@@ -275,6 +284,7 @@ async function runCiCompatibilityReport({
     capture,
     mockSdk,
     openclawPath,
+    openclawVersion,
     outDir,
     pluginRoot,
   });
@@ -314,6 +324,19 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function readOpenClawVersion(commandArgs) {
+  const index = commandArgs.indexOf("--openclaw-version");
+  if (index === -1) return null;
+  const version = commandArgs[index + 1];
+  if (!version || version.startsWith("-")) {
+    throw new Error("--openclaw-version requires a value");
+  }
+  if (version && (commandArgs.includes("--no-openclaw") || commandArgs.includes("--openclaw"))) {
+    throw new Error("--openclaw-version cannot be combined with --openclaw or --no-openclaw");
+  }
+  return version;
+}
+
 function findCaptureEntrypoint(commandArgs) {
   const flagsWithValues = new Set(["--output", "--plugin-root", "--sdk"]);
   const consumedIndexes = new Set();
@@ -452,13 +475,13 @@ function printHelp() {
 
 Usage:
   plugin-inspector
-  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
   plugin-inspector config [--plugin-root <path>] [--config <path>] [--json]
   plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--scripts] [--package-manager npm|pnpm|yarn|bun] [--dry-run] [--json] [--force]
-  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json]
-  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
-  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
-  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--author-facing] [--check] [--json]
+  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
+  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path> | --openclaw-version latest|beta|<exact> | --no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
   plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--allow-execute] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.

package/src/compatibility-report.js

@@ -351,6 +351,12 @@ function targetOpenClawTable(targetOpenClaw = {}) {
     [
       ["Configured path", targetOpenClaw.configuredPath ?? "-"],
       ["Status", targetOpenClaw.status],
+      ["Requested version", targetOpenClaw.requestedVersion ?? "-"],
+      ["Resolved version", targetOpenClaw.version ?? "-"],
+      ["Range eligibility version", targetOpenClaw.eligibilityVersion ?? "-"],
+      ["Source", targetOpenClaw.source ? `${targetOpenClaw.source.type}:${targetOpenClaw.source.package}` : "-"],
+      ["NPM dist-tag", targetOpenClaw.source?.distTag ?? "-"],
+      ["Prepared cache", targetOpenClaw.cache ? (targetOpenClaw.cache.hit ? "hit" : "miss") : "-"],
       ["Compat registry", targetOpenClaw.compatRegistryPath ?? "-"],
       ["Compat records", targetOpenClaw.compatRecordCount ?? 0],
       ["Compat status counts", Object.entries(statusCounts).map(([status, count]) => `${status}:${count}`).join(", ") || "-"],

package/src/config.js

@@ -195,7 +195,8 @@ async function readJsonIfExists(filePath) {
   if (!existsSync(filePath)) {
     return null;
   }
-  return JSON.parse(await readFile(filePath, "utf8"));
+  const contents = await readFile(filePath, "utf8");
+  return JSON.parse(contents.startsWith("\uFEFF") ? contents.slice(1) : contents);
 }
 
 export function packageId(packageName) {