@openclaw/plugin-inspector 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.1 - 2026-04-28
+
+### Added
+
+- Add grouped root facades: `pluginRoot`, `fixtureSuites`, `staticInspection`, `reports`, `contracts`, `ci`, `runtime`, and `synthetic`.
+- Expose contract capture, contract coverage, CI rollup, runtime profile, ref/profile diff, import-loop, and synthetic probe helpers from the root package API.
+- Add a release follow-through guard that fails when Crabpot scripts regress to the legacy `advanced.js` bundle.
+- Add a package-contents release guard for npm tarball entrypoints, examples, and README assets.
+
+### Changed
+
+- Move Crabpot integration scripts to the root public API while keeping Crabpot as the fixture corpus and report consumer.
+- Keep generic artifact writing out of the root API; Crabpot-owned runner scripts write their own JSON outputs.
+- Ship the README banner asset in the npm package so the published README does not reference a missing local image.
+- Document the grouped root import path for embedding harnesses without turning the README into a full API dump.
+
 ## 0.3.0 - 2026-04-27
 
 ### Added

package/README.md

@@ -18,6 +18,14 @@ npx @openclaw/plugin-inspector
 That runs `check`, writes report artifacts to `reports/`, and exits non-zero
 when compatibility breakages are found.
 
+Package-manager equivalents:
+
+```bash
+pnpm dlx @openclaw/plugin-inspector
+yarn dlx @openclaw/plugin-inspector
+bunx @openclaw/plugin-inspector
+```
+
 Add a local config and GitHub Actions workflow:
 
 ```bash
@@ -36,6 +44,18 @@ npm install --save-dev @openclaw/plugin-inspector
 npx plugin-inspector check
 ```
 
+With a local dev dependency, prefer package scripts so CI and local checks use
+the same command:
+
+```json
+{
+  "scripts": {
+    "plugin:check": "plugin-inspector inspect --no-openclaw",
+    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
+  }
+}
+```
+
 ## Commands
 
 ```bash
@@ -236,6 +256,26 @@ plugin-inspector report --config crabpot.config.json --out reports
 Use fixture suites when one repo wants to inspect many plugins. Use plugin-root
 `check` for normal plugin CI.
 
+## Library Use
+
+Most plugin repos should use the CLI. Harnesses can import grouped root helpers
+when they need to embed the inspector:
+
+```js
+import { pluginRoot, fixtureSuites, contracts, ci } from "@openclaw/plugin-inspector";
+
+const { report } = await pluginRoot.runCheck({
+  pluginRoot: process.cwd(),
+  openclawPath: false,
+});
+const capture = contracts.buildCapture({ report });
+const summary = await ci.buildSummary({ reports: { compatibility: report } });
+```
+
+The root package groups stable workflows as `pluginRoot`, `fixtureSuites`,
+`staticInspection`, `reports`, `contracts`, `ci`, `runtime`, and `synthetic`.
+Named exports remain available for existing automation.
+
 ## Mocking Model
 
 Default inspection is static, offline, and credential-free. Runtime capture is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",
@@ -43,14 +43,19 @@
   "files": [
     "src",
     "examples",
+    "docs/plugin-inspector-banner.jpg",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "check": "npm test && npm pack --dry-run",
+    "check": "npm test && npm run release:contents",
     "release:crabpot": "node scripts/check-crabpot-followthrough.mjs",
+    "release:contents": "node scripts/check-package-contents.mjs",
+    "release:plan": "node scripts/release-plan.mjs",
+    "release:readiness": "npm run release:local && npm run release:crabpot",
     "release:local": "npm run check",
+    "release:notes": "node scripts/release-notes.mjs --unreleased",
     "test": "node --test test/*.test.js"
   },
   "keywords": [

package/src/api.js

@@ -8,6 +8,24 @@ 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";
+import {
+  buildColdImportReadiness,
+  renderColdImportReadinessMarkdown,
+  validateColdImportReadiness,
+  writeColdImportReadiness,
+} from "./cold-import-readiness.js";
+import {
+  buildWorkspacePlan,
+  renderWorkspacePlanMarkdown,
+  validateWorkspacePlan,
+  writeWorkspacePlan,
+} from "./workspace-plan.js";
+import {
+  buildPlatformProbes,
+  renderPlatformProbesMarkdown,
+  validatePlatformProbes,
+  writePlatformProbes,
+} from "./platform-probes.js";
 
 export async function loadPluginConfig(options = {}) {
   if (options.config) {
@@ -87,6 +105,98 @@ export async function runFixtureSetReport(options = {}) {
   return { report, paths };
 }
 
+export async function buildFixtureSetColdImportReadiness(options = {}) {
+  const config = options.report ? null : await loadFixtureSetConfig(options);
+  const report =
+    options.report ??
+    (await inspectCompatibilityFixtureSet(config, {
+      generatedAt: options.generatedAt,
+      openclawPath: options.openclawPath,
+      targetOpenClaw: options.targetOpenClaw,
+    }));
+
+  return buildColdImportReadiness({
+    ...options,
+    report,
+    rootDir: options.rootDir ?? config?.rootDir ?? options.cwd,
+  });
+}
+
+export function renderFixtureSetColdImportReadinessMarkdown(readiness, options = {}) {
+  return renderColdImportReadinessMarkdown(readiness, options);
+}
+
+export async function writeFixtureSetColdImportReadiness(readiness, options = {}) {
+  return writeColdImportReadiness(readiness, options);
+}
+
+export async function runFixtureSetColdImportReadiness(options = {}) {
+  const readiness = await buildFixtureSetColdImportReadiness(options);
+  const paths = options.write === false ? null : await writeFixtureSetColdImportReadiness(readiness, options);
+  return { readiness, paths };
+}
+
+export async function buildFixtureSetWorkspacePlan(options = {}) {
+  const config = options.report ? null : await loadFixtureSetConfig(options);
+  const report =
+    options.report ??
+    (await inspectCompatibilityFixtureSet(config, {
+      generatedAt: options.generatedAt,
+      openclawPath: options.openclawPath,
+      targetOpenClaw: options.targetOpenClaw,
+    }));
+  const rootDir = options.rootDir ?? config?.rootDir ?? options.cwd;
+  const readiness = options.readiness ?? buildColdImportReadiness({ ...options, report, rootDir });
+
+  return buildWorkspacePlan({
+    ...options,
+    report,
+    readiness,
+    rootDir,
+  });
+}
+
+export function renderFixtureSetWorkspacePlanMarkdown(plan, options = {}) {
+  return renderWorkspacePlanMarkdown(plan, options);
+}
+
+export function validateFixtureSetWorkspacePlan(plan, options = {}) {
+  return validateWorkspacePlan(plan, options);
+}
+
+export async function writeFixtureSetWorkspacePlan(plan, options = {}) {
+  return writeWorkspacePlan(plan, options);
+}
+
+export async function runFixtureSetWorkspacePlan(options = {}) {
+  const plan = await buildFixtureSetWorkspacePlan(options);
+  const paths = options.write === false ? null : await writeFixtureSetWorkspacePlan(plan, options);
+  return { plan, paths };
+}
+
+export async function buildFixtureSetPlatformProbes(options = {}) {
+  const plan = options.plan ?? (await buildFixtureSetWorkspacePlan(options));
+  return buildPlatformProbes({ ...options, plan });
+}
+
+export function renderFixtureSetPlatformProbesMarkdown(report, options = {}) {
+  return renderPlatformProbesMarkdown(report, options);
+}
+
+export function validateFixtureSetPlatformProbes(report, options = {}) {
+  return validatePlatformProbes(report, options);
+}
+
+export async function writeFixtureSetPlatformProbes(report, options = {}) {
+  return writePlatformProbes(report, options);
+}
+
+export async function runFixtureSetPlatformProbes(options = {}) {
+  const report = await buildFixtureSetPlatformProbes(options);
+  const paths = options.write === false ? null : await writeFixtureSetPlatformProbes(report, options);
+  return { report, paths };
+}
+
 export async function runPluginCheck(options = {}) {
   const outDir = options.outDir ?? "reports";
   const config = await loadPluginConfig(options);
@@ -131,7 +241,7 @@ export async function setupPluginInspector(options = {}) {
   return writePluginInspectorInit(options);
 }
 
-export { createCaptureApi, renderTextSummary, writeCiOutputArtifacts };
+export { createCaptureApi, renderTextSummary, validateColdImportReadiness, writeCiOutputArtifacts };
 
 function executionAllowed(options) {
   return options.allowExecution === true || process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED === "1";

package/src/index.js

@@ -1,17 +1,239 @@
+import * as pluginApi from "./api.js";
+import * as ciPolicyApi from "./ci-policy.js";
+import * as ciSummaryApi from "./ci-summary.js";
+import * as configApi from "./config.js";
+import * as contractCaptureApi from "./contract-capture.js";
+import * as contractCoverageApi from "./contract-coverage.js";
+import * as executionResultsApi from "./execution-results.js";
+import * as importLoopProfileApi from "./import-loop-profile.js";
+import * as inspectorApi from "./inspector.js";
+import * as issuesApi from "./issues.js";
+import * as openClawTargetApi from "./openclaw-target.js";
+import * as profileDiffApi from "./profile-diff.js";
+import * as refDiffApi from "./ref-diff.js";
+import * as reportApi from "./report.js";
+import * as runtimeProfileApi from "./runtime-profile.js";
+import * as syntheticProbeSuiteApi from "./synthetic-probe-suite.js";
+import * as syntheticProbesApi from "./synthetic-probes.js";
+
+export const pluginRoot = Object.freeze({
+  loadConfig: pluginApi.loadPluginConfig,
+  inspect: pluginApi.inspectPluginRoot,
+  runCheck: pluginApi.runPluginCheck,
+  captureEntrypoint: pluginApi.capturePluginEntrypoint,
+  setup: pluginApi.setupPluginInspector,
+});
+
+export const fixtureSuites = Object.freeze({
+  loadConfig: configApi.loadInspectorConfig,
+  inspect: pluginApi.inspectCompatibilityFixtureSetConfig,
+  inspectStatic: pluginApi.inspectFixtureSetConfig,
+  runReport: pluginApi.runFixtureSetReport,
+  writeReports: pluginApi.writeFixtureSetReports,
+  renderReport: pluginApi.renderFixtureSetMarkdownReport,
+  renderIssues: pluginApi.renderFixtureSetIssuesReport,
+  buildColdImportReadiness: pluginApi.buildFixtureSetColdImportReadiness,
+  runColdImportReadiness: pluginApi.runFixtureSetColdImportReadiness,
+  writeColdImportReadiness: pluginApi.writeFixtureSetColdImportReadiness,
+  buildWorkspacePlan: pluginApi.buildFixtureSetWorkspacePlan,
+  runWorkspacePlan: pluginApi.runFixtureSetWorkspacePlan,
+  writeWorkspacePlan: pluginApi.writeFixtureSetWorkspacePlan,
+  buildPlatformProbes: pluginApi.buildFixtureSetPlatformProbes,
+  runPlatformProbes: pluginApi.runFixtureSetPlatformProbes,
+  writePlatformProbes: pluginApi.writeFixtureSetPlatformProbes,
+});
+
+export const staticInspection = Object.freeze({
+  loadConfig: configApi.loadInspectorConfig,
+  inspectSourceText: inspectorApi.inspectSourceText,
+  inspectPlugin: inspectorApi.inspectPlugin,
+  inspectFixtureSet: inspectorApi.inspectFixtureSet,
+});
+
+export const reports = Object.freeze({
+  renderMarkdown: reportApi.renderMarkdownReport,
+  renderTextSummary: pluginApi.renderTextSummary,
+  write: reportApi.writeReport,
+  issueId: issuesApi.issueId,
+  classifyIssueFinding: issuesApi.classifyIssueFinding,
+  knownIssueCodes: issuesApi.knownIssueCodes,
+  openClawTargetPathCandidates: openClawTargetApi.openClawTargetPathCandidates,
+});
+
+export const contracts = Object.freeze({
+  buildCapture: contractCaptureApi.buildContractCapture,
+  writeCapture: contractCaptureApi.writeContractCapture,
+  renderCapture: contractCaptureApi.renderContractCaptureMarkdown,
+  validateCapture: contractCaptureApi.validateContractCapture,
+  validateCoverage: contractCoverageApi.validateContractCoverage,
+  defaults: Object.freeze({
+    registrationAssertions: contractCaptureApi.defaultRegistrationAssertions,
+    registrationArguments: contractCaptureApi.defaultRegistrationArguments,
+    hookAssertions: contractCaptureApi.defaultHookAssertions,
+    hookEvents: contractCaptureApi.defaultHookEvents,
+    hookContexts: contractCaptureApi.defaultHookContexts,
+  }),
+});
+
+export const ci = Object.freeze({
+  buildSummary: ciSummaryApi.buildCiSummary,
+  writeSummary: ciSummaryApi.writeCiSummary,
+  renderSummary: ciSummaryApi.renderCiSummaryMarkdown,
+  readReports: ciSummaryApi.readCiReports,
+  deriveStatus: ciSummaryApi.deriveCiStatus,
+  buildPolicyReport: ciPolicyApi.buildCiPolicyReport,
+  writePolicyReport: ciPolicyApi.writeCiPolicyReport,
+  renderPolicyReport: ciPolicyApi.renderCiPolicyMarkdown,
+  validatePolicy: ciPolicyApi.validateCiPolicy,
+  validatePolicyReport: ciPolicyApi.validateCiPolicyReport,
+  buildExecutionResults: executionResultsApi.buildExecutionResultsReport,
+  writeExecutionResults: executionResultsApi.writeExecutionResultsReport,
+  renderExecutionResults: executionResultsApi.renderExecutionResultsMarkdown,
+  writeOutputs: pluginApi.writeCiOutputArtifacts,
+});
+
+export const runtime = Object.freeze({
+  buildProfile: runtimeProfileApi.buildRuntimeProfile,
+  writeProfile: runtimeProfileApi.writeRuntimeProfile,
+  renderProfile: runtimeProfileApi.renderRuntimeProfileMarkdown,
+  validateProfile: runtimeProfileApi.validateRuntimeProfile,
+  buildProfileDiff: profileDiffApi.buildProfileDiff,
+  writeProfileDiff: profileDiffApi.writeProfileDiff,
+  renderProfileDiff: profileDiffApi.renderProfileDiffMarkdown,
+  validateProfileDiff: profileDiffApi.validateProfileDiff,
+  buildRefDiff: refDiffApi.buildRefDiff,
+  writeRefDiff: refDiffApi.writeRefDiff,
+  renderRefDiff: refDiffApi.renderRefDiffMarkdown,
+  validateRefDiff: refDiffApi.validateRefDiff,
+  buildImportLoopProfile: importLoopProfileApi.buildImportLoopProfile,
+  writeImportLoopProfile: importLoopProfileApi.writeImportLoopProfile,
+  renderImportLoopProfile: importLoopProfileApi.renderImportLoopProfileMarkdown,
+  validateImportLoopProfile: importLoopProfileApi.validateImportLoopProfile,
+});
+
+export const synthetic = Object.freeze({
+  buildPlan: syntheticProbesApi.buildSyntheticProbePlan,
+  buildPlanFromReport: syntheticProbeSuiteApi.buildSyntheticProbePlanFromReport,
+  writePlan: syntheticProbesApi.writeSyntheticProbePlan,
+  renderPlan: syntheticProbesApi.renderSyntheticProbeMarkdown,
+  validatePlan: syntheticProbesApi.validateSyntheticProbePlan,
+  runCaptured: syntheticProbesApi.runCapturedSyntheticProbes,
+  registrationExecutionProfiles: syntheticProbesApi.syntheticRegistrationExecutionProfiles,
+  defaultHookEvents: syntheticProbesApi.defaultSyntheticHookEvents,
+  defaultHookContexts: syntheticProbesApi.defaultSyntheticHookContexts,
+  defaultRegistrationArguments: syntheticProbesApi.defaultSyntheticRegistrationArguments,
+});
+
 export {
   capturePluginEntrypoint,
+  buildFixtureSetColdImportReadiness,
+  buildFixtureSetPlatformProbes,
+  buildFixtureSetWorkspacePlan,
   createCaptureApi,
   inspectCompatibilityFixtureSetConfig,
   inspectFixtureSetConfig,
   inspectPluginRoot,
   loadPluginConfig,
+  renderFixtureSetColdImportReadinessMarkdown,
   renderFixtureSetIssuesReport,
   renderFixtureSetMarkdownReport,
+  renderFixtureSetPlatformProbesMarkdown,
+  renderFixtureSetWorkspacePlanMarkdown,
   renderTextSummary,
+  runFixtureSetColdImportReadiness,
+  runFixtureSetPlatformProbes,
   runFixtureSetReport,
+  runFixtureSetWorkspacePlan,
   runPluginCheck,
   setupPluginInspector,
+  validateColdImportReadiness,
+  validateFixtureSetPlatformProbes,
+  validateFixtureSetWorkspacePlan,
   writeCiOutputArtifacts,
+  writeFixtureSetColdImportReadiness,
+  writeFixtureSetPlatformProbes,
   writeFixtureSetReports,
+  writeFixtureSetWorkspacePlan,
   writePluginReports,
 } from "./api.js";
+export {
+  buildContractCapture,
+  defaultHookAssertions,
+  defaultHookContexts,
+  defaultHookEvents,
+  defaultRegistrationArguments,
+  defaultRegistrationAssertions,
+  renderContractCaptureMarkdown,
+  validateContractCapture,
+  writeContractCapture,
+} from "./contract-capture.js";
+export { validateContractCoverage } from "./contract-coverage.js";
+export {
+  buildCiPolicyReport,
+  defaultCiPolicyReportOptions,
+  renderCiPolicyMarkdown,
+  validateCiPolicy,
+  validateCiPolicyReport,
+  writeCiPolicyReport,
+} from "./ci-policy.js";
+export {
+  buildCiSummary,
+  defaultCiReportPaths,
+  deriveCiStatus,
+  readCiReports,
+  renderCiSummaryMarkdown,
+  writeCiSummary,
+} from "./ci-summary.js";
+export { loadInspectorConfig } from "./config.js";
+export {
+  buildExecutionResultsReport,
+  defaultExecutionResultsOptions,
+  renderExecutionResultsMarkdown,
+  writeExecutionResultsReport,
+} from "./execution-results.js";
+export {
+  buildImportLoopProfile,
+  defaultImportLoopProfileOptions,
+  renderImportLoopProfileMarkdown,
+  validateImportLoopProfile,
+  writeImportLoopProfile,
+} from "./import-loop-profile.js";
+export { classifyIssueFinding, issueId, knownIssueCodes } from "./issues.js";
+export { inspectFixtureSet, inspectPlugin, inspectSourceText } from "./inspector.js";
+export { openClawTargetPathCandidates } from "./openclaw-target.js";
+export {
+  buildProfileDiff,
+  defaultProfileDiffOptions,
+  renderProfileDiffMarkdown,
+  validateProfileDiff,
+  writeProfileDiff,
+} from "./profile-diff.js";
+export {
+  buildRefDiff,
+  defaultRefDiffDimensions,
+  defaultRefDiffOptions,
+  renderRefDiffMarkdown,
+  validateRefDiff,
+  writeRefDiff,
+} from "./ref-diff.js";
+export { renderMarkdownReport, writeReport } from "./report.js";
+export {
+  buildRuntimeProfile,
+  defaultRuntimeProfileCommands,
+  defaultRuntimeProfileOptions,
+  renderRuntimeProfileMarkdown,
+  validateRuntimeProfile,
+  writeRuntimeProfile,
+} from "./runtime-profile.js";
+export { buildSyntheticProbePlanFromReport } from "./synthetic-probe-suite.js";
+export {
+  buildSyntheticProbePlan,
+  defaultSyntheticHookContexts,
+  defaultSyntheticHookEvents,
+  defaultSyntheticRegistrationArguments,
+  renderSyntheticProbeMarkdown,
+  runCapturedSyntheticProbes,
+  syntheticRegistrationExecutionProfiles,
+  validateSyntheticProbePlan,
+  writeSyntheticProbePlan,
+} from "./synthetic-probes.js";