@openclaw/plugin-inspector 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.2.0 - 2026-04-27
+
+### Added
+
+- Add package.json `pluginInspector` config discovery for plugin-root checks.
+- Add `plugin-inspector config` for resolved plugin-root config summaries.
+- Add author-facing `plugin-inspector inspect` plugin-root flow.
+- Add CI-native SARIF and JUnit outputs; `plugin-inspector ci` writes them by default.
+
+### Changed
+
+- Make generated CI workflows use one `plugin-inspector ci --no-openclaw --runtime --mock-sdk` command.
+- Harden runtime capture for string handler registrations, parse-capable config schema helpers, and provider auth/catalog SDK mocks.
+
+## 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/README.md

@@ -35,17 +35,39 @@ npx plugin-inspector check
 
 ```bash
 npx @openclaw/plugin-inspector check
+npx @openclaw/plugin-inspector inspect
+npx @openclaw/plugin-inspector ci --no-openclaw
+npx @openclaw/plugin-inspector config
 npx @openclaw/plugin-inspector check --plugin-root ./plugins/weather
 npx @openclaw/plugin-inspector init --ci --package-manager pnpm
 ```
 
-`check` reads the current directory as one plugin unless `--plugin-root` is set.
-It writes:
+`check` and `inspect` read the current directory as one plugin unless
+`--plugin-root` is set. `inspect` is the friendly author-facing alias; `check`
+is kept for scripts. Both write:
 
 - `reports/plugin-inspector-report.json`
 - `reports/plugin-inspector-report.md`
 - `reports/plugin-inspector-issues.md`
 
+Use CI-native outputs when you want annotations or test-summary ingestion:
+
+```bash
+plugin-inspector inspect --no-openclaw --sarif --junit
+```
+
+That also writes:
+
+- `reports/plugin-inspector.sarif`
+- `reports/plugin-inspector.junit.xml`
+
+`config` prints the resolved plugin root, fixture id, seams, and capture
+settings before CI runs:
+
+```bash
+plugin-inspector config --json
+```
+
 Use `--no-openclaw` when CI should not compare against a local OpenClaw
 checkout:
 
@@ -53,8 +75,9 @@ checkout:
 plugin-inspector check --no-openclaw
 ```
 
-Use `plugin-inspector.config.json` when CI needs stable fixture metadata,
-expected seams, or runtime capture defaults:
+Use either `plugin-inspector.config.json` or a `package.json`
+`pluginInspector` block when CI needs stable fixture metadata, expected seams,
+or runtime capture defaults:
 
 ```json
 {
@@ -83,9 +106,32 @@ Then run:
 plugin-inspector check --config plugin-inspector.config.json
 ```
 
+For a single plugin package, the same config can live in `package.json`:
+
+```json
+{
+  "scripts": {
+    "plugin:check": "plugin-inspector inspect --no-openclaw"
+  },
+  "pluginInspector": {
+    "version": 1,
+    "plugin": {
+      "id": "weather",
+      "priority": "high",
+      "seams": ["dynamic-tool"],
+      "sourceRoot": "src"
+    },
+    "capture": {
+      "mockSdk": true
+    }
+  }
+}
+```
+
 `init --ci` writes this shape for you, plus
 `.github/workflows/plugin-inspector.yml`. Copy-ready examples also live in
 `examples/plugin-inspector.config.json` and
+`examples/package-json-plugin-inspector.json` and
 `examples/github-actions-plugin-inspector.yml`.
 
 ## Runtime Capture
@@ -121,8 +167,8 @@ Minimal package scripts:
 ```json
 {
   "scripts": {
-    "plugin:check": "plugin-inspector check --no-openclaw",
-    "plugin:check:runtime": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --runtime --mock-sdk"
+    "plugin:check": "plugin-inspector inspect --no-openclaw",
+    "plugin:ci": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector ci --no-openclaw --runtime --mock-sdk"
   }
 }
 ```
@@ -147,8 +193,7 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
-      - run: npx @openclaw/plugin-inspector check --no-openclaw
-      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --no-openclaw --runtime --mock-sdk
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk
       - uses: actions/upload-artifact@v5
         if: always()
         with:
@@ -156,6 +201,9 @@ jobs:
           path: reports/plugin-inspector-*
 ```
 
+`ci` writes the normal report, CI summary, SARIF, and JUnit files by default.
+Pass `--no-sarif` or `--no-junit` only if your CI surface cannot consume them.
+
 ## Fixture Suites
 
 Fixture-set configs are still supported for crabpot-style compatibility suites:

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

@@ -15,8 +15,7 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
-      - run: npx @openclaw/plugin-inspector check --no-openclaw
-      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --no-openclaw --runtime --mock-sdk
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk
       - uses: actions/upload-artifact@v5
         if: always()
         with:

package/examples/package-json-plugin-inspector.json

@@ -0,0 +1,21 @@
+{
+  "scripts": {
+    "plugin:check": "plugin-inspector inspect --no-openclaw",
+    "plugin:ci": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector ci --no-openclaw --runtime --mock-sdk"
+  },
+  "pluginInspector": {
+    "version": 1,
+    "plugin": {
+      "id": "weather",
+      "priority": "high",
+      "seams": ["dynamic-tool"],
+      "sourceRoot": "src",
+      "expect": {
+        "registrations": ["registerTool"]
+      }
+    },
+    "capture": {
+      "mockSdk": true
+    }
+  }
+}

package/package.json

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

package/src/advanced.js

@@ -33,6 +33,14 @@ export {
   renderCiSummaryMarkdown,
   writeCiSummary,
 } from "./ci-summary.js";
+export {
+  buildSarifReport,
+  defaultJunitPath,
+  defaultSarifPath,
+  renderJunitXml,
+  reportFindings,
+  writeCiOutputArtifacts,
+} from "./ci-outputs.js";
 export {
   buildContractProbes,
   contractProbeRules,
@@ -100,6 +108,7 @@ export {
   openClawTargetPathCandidates,
   parseCompatRecordEntries,
   parseExportedStringArray,
+  parsePluginSdkEntrypointSpecifiers,
   parsePluginSdkExports,
   parseTypeFields,
   readOpenClawTargetSurface,
@@ -121,6 +130,7 @@ export {
   loadPluginRootConfig,
   normalizeInspectorConfig,
   normalizePluginRootConfig,
+  packageJsonConfigKeys,
   packageId,
   validateInspectorConfig,
 } from "./config.js";

package/src/api.js

@@ -4,6 +4,7 @@ import { loadInspectorConfig, loadPluginRootConfig } from "./config.js";
 import { writePluginInspectorInit } from "./init.js";
 import { captureEntrypoint } from "./inspector.js";
 import { renderTextSummary, writeCompatibilityReport } from "./report.js";
+import { writeCiOutputArtifacts } from "./ci-outputs.js";
 import { buildRuntimeCaptureReport, writeRuntimeCaptureReport } from "./runtime-capture-report.js";
 import { inspectCompatibilityFixtureSet, inspectFixtureSet } from "./inspector.js";
 
@@ -88,4 +89,4 @@ export async function setupPluginInspector(options = {}) {
   return writePluginInspectorInit(options);
 }
 
-export { createCaptureApi, renderTextSummary };
+export { createCaptureApi, renderTextSummary, writeCiOutputArtifacts };

package/src/capture-api.js

@@ -223,6 +223,7 @@ function createStoreContext() {
 
 function registrationObject(args, defaults) {
   const first = args[0];
+  const callable = firstCallable(args);
   if (first && typeof first === "object") {
     return {
       ...defaults,
@@ -232,13 +233,29 @@ function registrationObject(args, defaults) {
     };
   }
   if (typeof first === "string") {
-    return {
+    return withCallableDefaults({
       ...defaults,
       name: first,
       id: defaults.id,
-    };
+    }, callable);
   }
-  return { ...defaults };
+  return withCallableDefaults({ ...defaults }, callable);
+}
+
+function firstCallable(args) {
+  return args.find((arg) => typeof arg === "function");
+}
+
+function withCallableDefaults(value, callable) {
+  if (!callable) {
+    return value;
+  }
+  return {
+    ...value,
+    handler: typeof value.handler === "function" ? value.handler : callable,
+    run: typeof value.run === "function" ? value.run : callable,
+    execute: typeof value.execute === "function" ? value.execute : callable,
+  };
 }
 
 function summarizeArguments(args) {

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-outputs.js

@@ -0,0 +1,235 @@
+import path from "node:path";
+import { writeArtifacts } from "./artifacts.js";
+
+export const defaultSarifPath = "plugin-inspector.sarif";
+export const defaultJunitPath = "plugin-inspector.junit.xml";
+
+export async function writeCiOutputArtifacts(report, options = {}) {
+  const outDir = path.resolve(options.cwd ?? process.cwd(), options.outDir ?? "reports");
+  const artifacts = [];
+
+  if (options.sarifPath) {
+    artifacts.push({
+      name: "sarifPath",
+      path: path.resolve(outDir, options.sarifPath),
+      json: buildSarifReport(report),
+    });
+  }
+
+  if (options.junitPath) {
+    artifacts.push({
+      name: "junitPath",
+      path: path.resolve(outDir, options.junitPath),
+      content: renderJunitXml(report),
+    });
+  }
+
+  if (artifacts.length === 0) {
+    return {};
+  }
+
+  return writeArtifacts(artifacts, { check: options.check });
+}
+
+export function buildSarifReport(report) {
+  const findings = reportFindings(report);
+  const rules = [...new Map(findings.map((finding) => [finding.code, sarifRule(finding)])).values()];
+  const fixtureById = new Map((report.fixtures ?? []).map((fixture) => [fixture.id, fixture]));
+
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "plugin-inspector",
+            informationUri: "https://github.com/openclaw/plugin-inspector",
+            rules,
+          },
+        },
+        results: findings.map((finding) => sarifResult(finding, fixtureById)),
+      },
+    ],
+  };
+}
+
+export function renderJunitXml(report) {
+  const findings = reportFindings(report);
+  const testcases = findings.length > 0 ? findings.map(junitFindingTestcase) : [junitPassingTestcase(report)];
+  const failures = findings.filter(isBlockingFinding).length;
+  const tests = testcases.length;
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuite name="plugin-inspector" tests="${tests}" failures="${failures}" errors="0" skipped="0">`,
+    ...testcases,
+    "</testsuite>",
+    "",
+  ].join("\n");
+}
+
+export function reportFindings(report) {
+  const findings = new Map();
+  for (const finding of [...(report.breakages ?? []), ...(report.warnings ?? []), ...(report.suggestions ?? [])]) {
+    findings.set(findingKey(finding), finding);
+  }
+  for (const issue of report.issues ?? []) {
+    const finding = issueToFinding(issue);
+    findings.set(findingKey(finding), {
+      ...findings.get(findingKey(finding)),
+      ...finding,
+    });
+  }
+  return [...findings.values()];
+}
+
+function issueToFinding(issue) {
+  return {
+    fixture: issue.fixture,
+    code: issue.code,
+    level: issue.status === "blocking" ? "breakage" : "warning",
+    message: issue.title,
+    evidence: issue.evidence ?? [],
+    severity: issue.severity,
+    issueClass: issue.issueClass,
+  };
+}
+
+function findingKey(finding) {
+  return [
+    finding.fixture ?? "",
+    finding.code ?? "",
+    ...normalizeEvidence(finding.evidence),
+  ].join("\n");
+}
+
+function sarifRule(finding) {
+  return {
+    id: finding.code,
+    shortDescription: {
+      text: finding.code,
+    },
+    fullDescription: {
+      text: finding.message ?? finding.code,
+    },
+    defaultConfiguration: {
+      level: sarifLevel(finding),
+    },
+  };
+}
+
+function sarifResult(finding, fixtureById) {
+  return {
+    ruleId: finding.code,
+    level: sarifLevel(finding),
+    message: {
+      text: finding.message ?? finding.code,
+    },
+    locations: [sarifLocation(finding, fixtureById)],
+    properties: {
+      fixture: finding.fixture,
+      severity: finding.severity ?? finding.level,
+      issueClass: finding.issueClass,
+      evidence: normalizeEvidence(finding.evidence),
+    },
+  };
+}
+
+function sarifLocation(finding, fixtureById) {
+  const parsed = parseEvidenceLocation(normalizeEvidence(finding.evidence)[0]);
+  const fixture = fixtureById.get(finding.fixture);
+  const uri = parsed?.uri ?? fixture?.path ?? ".";
+  return {
+    physicalLocation: {
+      artifactLocation: {
+        uri: normalizeUri(uri),
+      },
+      region: {
+        startLine: parsed?.line ?? 1,
+      },
+    },
+  };
+}
+
+function parseEvidenceLocation(evidence) {
+  if (!evidence) {
+    return null;
+  }
+
+  const ref = evidence.includes(" @ ") ? evidence.split(" @ ").pop() : evidence;
+  const match = /^(?<uri>.+?):(?<line>\d+)(?::\d+)?$/.exec(ref);
+  if (!match?.groups?.uri) {
+    return null;
+  }
+  return {
+    uri: match.groups.uri,
+    line: Number(match.groups.line),
+  };
+}
+
+function junitFindingTestcase(finding) {
+  const classname = `plugin-inspector.${xmlName(finding.fixture ?? "unknown")}`;
+  const name = `${finding.level ?? "finding"}:${finding.code}`;
+  const output = normalizeEvidence(finding.evidence).join("\n");
+  if (!isBlockingFinding(finding)) {
+    return [
+      `  <testcase classname="${escapeXml(classname)}" name="${escapeXml(name)}">`,
+      output ? `    <system-out>${escapeXml(output)}</system-out>` : "",
+      "  </testcase>",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  return [
+    `  <testcase classname="${escapeXml(classname)}" name="${escapeXml(name)}">`,
+    `    <failure message="${escapeXml(finding.message ?? finding.code)}">${escapeXml(output || finding.message || finding.code)}</failure>`,
+    "  </testcase>",
+  ].join("\n");
+}
+
+function junitPassingTestcase(report) {
+  return `  <testcase classname="plugin-inspector" name="status:${escapeXml(report.status ?? "pass")}"/>`;
+}
+
+function isBlockingFinding(finding) {
+  return finding.level === "breakage" || finding.status === "blocking" || finding.severity === "P0";
+}
+
+function sarifLevel(finding) {
+  if (isBlockingFinding(finding) || finding.severity === "P1") {
+    return "error";
+  }
+  if (finding.level === "warning" || finding.severity === "P2") {
+    return "warning";
+  }
+  return "note";
+}
+
+function normalizeEvidence(evidence) {
+  if (Array.isArray(evidence)) {
+    return evidence.map(String);
+  }
+  if (evidence == null) {
+    return [];
+  }
+  return [String(evidence)];
+}
+
+function normalizeUri(uri) {
+  return String(uri).replaceAll(path.sep, "/");
+}
+
+function xmlName(value) {
+  return String(value).replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

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",