@openclaw/plugin-inspector 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.3 - 2026-04-27
+
+### Added
+
+- Add reserved bundled-plugin SDK import detection so external plugins get explicit compatibility findings for private OpenClaw SDK shims.
+- Add packaged workspace capture and synthetic-probe helper CLIs for generated isolated workspace plans.
+
+### Changed
+
+- Make `plugin-inspector ci` write compatibility-backed CI summary artifacts instead of the legacy inventory report.
+- Default packaged helper captures to the mocked OpenClaw SDK while preserving `--real-sdk` opt-in behavior.
+- Detect the default runtime capture artifact at `reports/plugin-inspector-runtime-capture.json`.
+- Report the actual log count in CLI text summaries.
+
 ## 0.1.2 - 2026-04-27
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/advanced.js

@@ -100,6 +100,7 @@ export {
   openClawTargetPathCandidates,
   parseCompatRecordEntries,
   parseExportedStringArray,
+  parsePluginSdkEntrypointSpecifiers,
   parsePluginSdkExports,
   parseTypeFields,
   readOpenClawTargetSurface,

package/src/capture-cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { captureEntrypoint, writeArtifacts } from "./advanced.js";
+
+const args = process.argv.slice(2);
+
+try {
+  await run(args);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+
+async function run(commandArgs) {
+  const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
+  const outputPath = readFlag(commandArgs, "--output");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? true;
+
+  if (!entrypoint) {
+    throw new Error("capture requires an entrypoint path");
+  }
+  if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+    throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+  }
+
+  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
+  const json = `${JSON.stringify(result, null, 2)}\n`;
+  if (outputPath) {
+    await writeArtifacts([{ path: outputPath, content: json }]);
+  } else {
+    process.stdout.write(json);
+  }
+}
+
+function readFlag(commandArgs, name) {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) {
+    return null;
+  }
+  return commandArgs[index + 1] ?? null;
+}
+
+function readMockSdkFlag(commandArgs) {
+  const sdk = readFlag(commandArgs, "--sdk");
+  if (sdk === "mock") {
+    return true;
+  }
+  if (sdk === "real") {
+    return false;
+  }
+  if (sdk && !["mock", "real"].includes(sdk)) {
+    throw new Error("--sdk must be mock or real");
+  }
+  if (commandArgs.includes("--mock-sdk")) {
+    return true;
+  }
+  if (commandArgs.includes("--real-sdk")) {
+    return false;
+  }
+  return undefined;
+}

package/src/ci-summary.js

@@ -5,7 +5,7 @@ import { readOptionalJsonFile } from "./json-file.js";
 
 export const defaultCiReportPaths = {
   compatibility: "reports/plugin-inspector-report.json",
-  capture: "reports/plugin-inspector-capture.json",
+  capture: "reports/plugin-inspector-runtime-capture.json",
   synthetic: "reports/plugin-inspector-synthetic-probes.json",
   coldImport: "reports/plugin-inspector-cold-import.json",
   workspace: "reports/plugin-inspector-workspace-plan.json",

package/src/cli.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
+import path from "node:path";
 import {
   renderTextSummary,
   runPluginCheck,
 } from "./index.js";
 import {
+  buildCiSummary,
   captureEntrypoint,
+  inspectCompatibilityFixtureSet,
   inspectFixtureSet,
   loadInspectorConfig,
+  writeCiSummary,
+  writeCompatibilityReport,
   writePluginInspectorInit,
   writeArtifacts,
   writeReport,
@@ -23,8 +28,10 @@ try {
     await runCheck(commandArgs);
   } else if (command === "init") {
     await runInit(commandArgs);
-  } else if (command === "inspect" || command === "report" || command === "ci") {
+  } else if (command === "inspect" || command === "report") {
     await runReport(command, commandArgs);
+  } else if (command === "ci") {
+    await runCi(commandArgs);
   } else if (command === "capture") {
     await runCapture(commandArgs);
   } else {
@@ -95,6 +102,62 @@ async function runReport(command, commandArgs) {
   }
 }
 
+async function runCi(commandArgs) {
+  const configPath = readFlag(commandArgs, "--config");
+  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 json = commandArgs.includes("--json");
+  const { report, reportDir } = await runCiCompatibilityReport({
+    configPath,
+    openclawPath,
+    outDir,
+    pluginRoot,
+  });
+
+  const summary = await buildCiSummary({
+    artifactBaseDir: reportDir,
+    reportPaths: {
+      compatibility: "plugin-inspector-report.json",
+    },
+    reports: {
+      compatibility: report,
+    },
+  });
+  await writeCiSummary(summary, {
+    jsonPath: path.join(reportDir, "plugin-inspector-ci-summary.json"),
+    markdownPath: path.join(reportDir, "plugin-inspector-ci-summary.md"),
+  });
+
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(renderCiTextSummary(summary));
+  }
+
+  if (summary.status !== "pass") {
+    throw new Error("plugin-inspector ci summary failed");
+  }
+}
+
+async function runCiCompatibilityReport({ configPath, openclawPath, outDir, pluginRoot }) {
+  if (configPath) {
+    const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
+    const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
+    await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
+    return {
+      report,
+      reportDir: path.resolve(config.rootDir, outDir),
+    };
+  }
+
+  const { report } = await runPluginCheck({ pluginRoot, outDir, openclawPath });
+  return {
+    report,
+    reportDir: path.resolve(pluginRoot ?? process.cwd(), outDir),
+  };
+}
+
 async function runCapture(commandArgs) {
   const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
   const outputPath = readFlag(commandArgs, "--output");
@@ -154,6 +217,15 @@ function readMockSdkFlag(commandArgs) {
   return undefined;
 }
 
+function renderCiTextSummary(summary) {
+  return [
+    `Status: ${summary.status.toUpperCase()}`,
+    `Breakages: ${summary.summary.breakages}`,
+    `Issues: ${summary.summary.issues}`,
+    `Artifacts: ${Object.values(summary.artifacts).filter(Boolean).length}`,
+  ].join("\n");
+}
+
 function printHelp() {
   console.log(`plugin-inspector
 
@@ -163,7 +235,7 @@ Usage:
   plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--package-manager npm|pnpm|yarn|bun] [--force]
   plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
   plugin-inspector inspect --config <path> [--out <dir>] [--check] [--json]
-  plugin-inspector ci --config <path> [--out <dir>]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--json]
   PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.

package/src/contract-probes.js

@@ -29,6 +29,11 @@ export const contractProbeRules = {
     contract: "Every observed OpenClaw plugin SDK import remains exported by the target OpenClaw package.",
     target: "sdk-alias",
   },
+  "reserved-sdk-import": {
+    id: "sdk.import.reserved-bundled-plugin-boundary",
+    contract: "External plugins use documented public SDK subpaths instead of reserved bundled-plugin compatibility shims.",
+    target: "sdk-import",
+  },
   "provider-auth-env-vars": {
     id: "manifest.compat.provider-auth-env-vars",
     contract: "Legacy provider auth env metadata continues to map into config/help surfaces.",

package/src/fixture-summary.js

@@ -626,7 +626,12 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
 
   const sdkExports = new Set(targetOpenClaw.sdkExports);
   const unknownImports = fixtureReport.sdkImportDetails.filter((sdkImport) => !sdkExports.has(sdkImport.specifier));
-  if (unknownImports.length === 0) {
+  const reservedSdkExports = new Set(targetOpenClaw.reservedSdkExports ?? []);
+  const reservedImports = fixtureReport.sdkImportDetails.filter((sdkImport) =>
+    reservedSdkExports.has(sdkImport.specifier),
+  );
+
+  if (reservedImports.length === 0 && unknownImports.length === 0) {
     logs.push({
       fixture: fixture.id,
       code: "sdk-exports-present",
@@ -637,21 +642,40 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
     return;
   }
 
-  warnings.push({
-    fixture: fixture.id,
-    code: "sdk-export-missing",
-    level: "warning",
-    message: "fixture imports plugin SDK aliases that are not exported by the target OpenClaw package",
-    evidence: detailEvidence(unknownImports, "specifier"),
-    compatRecord: "plugin-sdk-export-aliases",
-  });
-  decisions.push({
-    fixture: fixture.id,
-    decision: "core-compat-adapter",
-    seam: "sdk-alias",
-    action: "Restore the package export alias or publish a versioned migration map before cold-importing old plugins.",
-    evidence: unique(unknownImports.map((sdkImport) => sdkImport.specifier)).join(", "),
-  });
+  if (unknownImports.length > 0) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "sdk-export-missing",
+      level: "warning",
+      message: "fixture imports plugin SDK aliases that are not exported by the target OpenClaw package",
+      evidence: detailEvidence(unknownImports, "specifier"),
+      compatRecord: "plugin-sdk-export-aliases",
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "core-compat-adapter",
+      seam: "sdk-alias",
+      action: "Restore the package export alias or publish a versioned migration map before cold-importing old plugins.",
+      evidence: unique(unknownImports.map((sdkImport) => sdkImport.specifier)).join(", "),
+    });
+  }
+
+  if (reservedImports.length > 0) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "reserved-sdk-import",
+      level: "warning",
+      message: "fixture imports reserved bundled-plugin SDK compatibility subpaths",
+      evidence: detailEvidence(reservedImports, "specifier"),
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "sdk-import",
+      action: "Move the plugin to documented public SDK subpaths or plugin-local helpers before relying on this compatibility shim.",
+      evidence: unique(reservedImports.map((sdkImport) => sdkImport.specifier)).join(", "),
+    });
+  }
 }
 
 function classifyManifestFieldCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions }) {

package/src/issues.js

@@ -32,6 +32,7 @@ export const knownIssueCodes = new Set([
   "provider-auth-env-vars",
   "registration-capture-gap",
   "runtime-tool-capture",
+  "reserved-sdk-import",
   "sdk-export-missing",
 ]);
 
@@ -78,6 +79,12 @@ export const issueMetadataByCode = {
     decision: "core-compat-adapter",
     title: "plugin SDK import aliases are missing from target package exports",
   },
+  "reserved-sdk-import": {
+    severity: "P1",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "plugin imports reserved bundled-plugin SDK compatibility subpaths",
+  },
   "missing-compat-record": {
     severity: "P1",
     owner: "core",
@@ -310,6 +317,7 @@ function issueClassFor(code, options) {
       "package-openclaw-entry-missing",
       "package-openclaw-metadata-missing",
       "package-plugin-api-compat-missing",
+      "reserved-sdk-import",
     ].includes(code)
   ) {
     return "upstream-metadata";

package/src/openclaw-target.js

@@ -31,6 +31,7 @@ export async function readOpenClawTargetSurface(options = {}) {
   const apiBuilderPath = path.join(resolvedPath, "src/plugins/api-builder.ts");
   const capturedRegistrationPath = path.join(resolvedPath, "src/plugins/captured-registration.ts");
   const manifestTypesPath = path.join(resolvedPath, "src/plugins/manifest.ts");
+  const pluginSdkEntrypointsPath = path.join(resolvedPath, "src/plugin-sdk/entrypoints.ts");
   const packagePath = path.join(resolvedPath, "package.json");
 
   const registrySource = await readFile(registryPath, "utf8");
@@ -48,6 +49,18 @@ export async function readOpenClawTargetSurface(options = {}) {
   const sdkExports = existsSync(packagePath)
     ? parsePluginSdkExports(JSON.parse(await readFile(packagePath, "utf8")))
     : [];
+  const pluginSdkEntrypointsSource = existsSync(pluginSdkEntrypointsPath)
+    ? await readFile(pluginSdkEntrypointsPath, "utf8")
+    : "";
+  const reservedSdkExports = pluginSdkEntrypointsSource
+    ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "reservedBundledPluginSdkEntrypoints")
+    : [];
+  const supportedFacadeSdkExports = pluginSdkEntrypointsSource
+    ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "supportedBundledFacadeSdkEntrypoints")
+    : [];
+  const publicPluginOwnedSdkExports = pluginSdkEntrypointsSource
+    ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "publicPluginOwnedSdkEntrypoints")
+    : [];
 
   return {
     configuredPath: requestedPath,
@@ -69,6 +82,13 @@ export async function readOpenClawTargetSurface(options = {}) {
     packagePath: existsSync(packagePath) ? relativePath(rootDir, packagePath) : null,
     sdkExportCount: sdkExports.length,
     sdkExports,
+    pluginSdkEntrypointsPath: existsSync(pluginSdkEntrypointsPath)
+      ? relativePath(rootDir, pluginSdkEntrypointsPath)
+      : null,
+    reservedSdkExportCount: reservedSdkExports.length,
+    reservedSdkExports,
+    supportedFacadeSdkExports,
+    publicPluginOwnedSdkExports,
     manifestTypesPath: existsSync(manifestTypesPath) ? relativePath(rootDir, manifestTypesPath) : null,
     manifestFieldCount: manifestFields.length,
     manifestFields,
@@ -149,11 +169,18 @@ function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status
     apiRegistrars: [],
     capturedRegistrars: [],
     sdkExports: [],
+    reservedSdkExports: [],
+    supportedFacadeSdkExports: [],
+    publicPluginOwnedSdkExports: [],
     manifestFields: [],
     manifestContractFields: [],
   };
 }
 
+export function parsePluginSdkEntrypointSpecifiers(source, exportName) {
+  return parseExportedStringArray(source, exportName).map((entrypoint) => `openclaw/plugin-sdk/${entrypoint}`).sort();
+}
+
 function parseCapturedRegistrars(source) {
   return unique([...source.matchAll(/^\s*(register[A-Za-z0-9]+)\s*\(/gm)].map((match) => match[1])).sort();
 }

package/src/report.js

@@ -160,6 +160,7 @@ export async function buildCompatibilityReport(options = {}) {
       warningCount: warnings.length,
       suggestionCount: suggestions.length,
       decisionCount: decisions.length,
+      logCount: logs.length,
       issueCount: issues.length,
       p0IssueCount: issues.filter((issue) => issue.severity === "P0").length,
       p1IssueCount: issues.filter((issue) => issue.severity === "P1").length,

package/src/synthetic-probes-cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { mkdtemp, rm } from "node:fs/promises";
+import { register } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { captureEntrypoint, runCapturedSyntheticProbes, writeArtifacts } from "./advanced.js";
+import { createMockSdkPackage } from "./sdk-mock.js";
+
+const args = process.argv.slice(2);
+
+try {
+  await run(args);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+
+async function run(commandArgs) {
+  const entrypoint = readFlag(commandArgs, "--entrypoint") ?? commandArgs.find((arg) => !arg.startsWith("-"));
+  const outputPath = readFlag(commandArgs, "--output");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root");
+  const includeLifecycle = commandArgs.includes("--include-lifecycle");
+  const includeChannelRuntime = commandArgs.includes("--include-channel-runtime");
+  const includeProviderCapabilities = commandArgs.includes("--include-provider-capabilities");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? true;
+
+  if (!entrypoint) {
+    throw new Error("synthetic probes require --entrypoint <path>");
+  }
+  if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+    throw new Error("synthetic probes import plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+  }
+
+  const capture = await captureForSyntheticProbes(entrypoint, {
+    mockSdk,
+    pluginRoot,
+    apiOptions: { retainHandlers: true },
+  });
+  const results = await runCapturedSyntheticProbes(capture, {
+    includeLifecycle,
+    includeChannelRuntime,
+    includeProviderCapabilities,
+  });
+  const json = `${JSON.stringify(results, null, 2)}\n`;
+
+  if (outputPath) {
+    await writeArtifacts([{ path: outputPath, content: json }]);
+  } else {
+    process.stdout.write(json);
+  }
+}
+
+async function captureForSyntheticProbes(entrypoint, options) {
+  if (options.mockSdk !== true) {
+    return captureEntrypoint(entrypoint, options);
+  }
+
+  const resolvedEntrypoint = path.resolve(process.cwd(), entrypoint);
+  const pluginRoot = path.resolve(process.cwd(), options.pluginRoot ?? path.dirname(resolvedEntrypoint));
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-synthetic-mock-sdk-"));
+  try {
+    const { loaderPath } = await createMockSdkPackage(workspace, { pluginRoot });
+    register(pathToFileURL(loaderPath));
+    return captureEntrypoint(entrypoint, {
+      ...options,
+      mockSdk: false,
+      pluginRoot,
+    });
+  } finally {
+    await rm(workspace, { force: true, recursive: true });
+  }
+}
+
+function readFlag(commandArgs, name) {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) {
+    return null;
+  }
+  return commandArgs[index + 1] ?? null;
+}
+
+function readMockSdkFlag(commandArgs) {
+  const sdk = readFlag(commandArgs, "--sdk");
+  if (sdk === "mock") {
+    return true;
+  }
+  if (sdk === "real") {
+    return false;
+  }
+  if (sdk && !["mock", "real"].includes(sdk)) {
+    throw new Error("--sdk must be mock or real");
+  }
+  if (commandArgs.includes("--mock-sdk")) {
+    return true;
+  }
+  if (commandArgs.includes("--real-sdk")) {
+    return false;
+  }
+  return undefined;
+}

package/src/workspace-plan.js

@@ -1,15 +1,16 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
 import { buildColdImportReadiness } from "./cold-import-readiness.js";
 import { normalizeRepoPath, posixJoin, slugForArtifact } from "./path-utils.js";
 
 export const defaultWorkspacePlanOptions = {
-  captureScript: "plugin-inspector-capture",
+  captureScript: null,
   optInEnv: "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1",
   resultsRoot: ".plugin-inspector/results",
-  syntheticProbeScript: "plugin-inspector-synthetic-probes",
+  syntheticProbeScript: null,
   workspaceRoot: ".plugin-inspector/workspaces",
 };
 
@@ -450,12 +451,23 @@ function runCommand(packageManager, script) {
 
 function captureCommand(settings, fixtureId, entrypoint, workspacePath) {
   const loader = entrypoint.blockers.some((blocker) => blocker.code === "ts-loader-required") ? " --import tsx" : "";
-  return `${settings.optInEnv} node${loader} ${settings.captureScript} ${entrypoint.specifier} --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture")}`;
+  const script = helperScript(settings, workspacePath, settings.captureScript, "capture-cli.js");
+  return `${settings.optInEnv} node${loader} ${script} ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture")}`;
 }
 
 function syntheticProbeCommand(settings, fixtureId, entrypoint, workspacePath) {
   const loader = entrypoint.blockers.some((blocker) => blocker.code === "ts-loader-required") ? " --import tsx" : "";
-  return `${settings.optInEnv} node${loader} ${settings.syntheticProbeScript} --entrypoint ${entrypoint.specifier} --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic")}`;
+  const script = helperScript(settings, workspacePath, settings.syntheticProbeScript, "synthetic-probes-cli.js");
+  return `${settings.optInEnv} node${loader} ${script} --entrypoint ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic")}`;
+}
+
+function helperScript(settings, workspacePath, configuredScript, helperFileName) {
+  if (configuredScript) {
+    return configuredScript;
+  }
+  const helperPath = fileURLToPath(new URL(`./${helperFileName}`, import.meta.url));
+  const workspaceFsPath = path.join(settings.rootDir, workspacePath);
+  return repoRelative(path.relative(workspaceFsPath, helperPath));
 }
 
 function targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath) {