@openclaw/plugin-inspector 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1 - 2026-04-27
+
+### Changed
+
+- Refresh npm package docs with the simplified CLI-first README and public API surface cleanup.
+
 ## 0.1.0 - 2026-04-27
 
 Initial public package release for `@openclaw/plugin-inspector`.

package/README.md

@@ -1,25 +1,22 @@
-# plugin-inspector
+<img src="docs/plugin-inspector-banner.jpg" alt="openclaw plugin inspector banner"/>
+
+# 💊 OpenClaw Plugin Inspector
 
 `plugin-inspector` is the reusable OpenClaw plugin compatibility inspector. It
 wraps the static inspection, registration capture, and report model prototyped
 in crabpot into an npm-publishable package.
 
-No npm package has been published yet.
-
 ## Install
 
-During development, use a local checkout or packed tarball:
+Install it as a dev dependency in a plugin repo:
 
 ```bash
-npm install --save-dev ../plugin-inspector
-npx plugin-inspector check --no-openclaw
+npm install --save-dev @openclaw/plugin-inspector
 ```
 
-After the package is published, plugin repos should install it as a dev
-dependency and run it from the plugin root:
+Then run it from the plugin root:
 
 ```bash
-npm install --save-dev @openclaw/plugin-inspector
 npx @openclaw/plugin-inspector check
 ```
 
@@ -143,101 +140,6 @@ jobs:
           path: reports/plugin-inspector-*
 ```
 
-## API
-
-```js
-import {
-  buildCiSummary,
-  buildCiPolicyReport,
-  buildColdImportReadiness,
-  buildContractCapture,
-  buildExecutionResultsReport,
-  buildImportLoopProfile,
-  buildPlatformProbes,
-  buildProfileDiff,
-  buildRefDiff,
-  buildRuntimeProfile,
-  buildRuntimeCaptureReport,
-  buildWorkspacePlan,
-  createCaptureApi,
-  inspectFixtureSet,
-  loadInspectorConfig,
-  readOpenClawTargetSurface,
-  renderCiPolicyMarkdown,
-  renderColdImportReadinessMarkdown,
-  renderContractCaptureMarkdown,
-  renderExecutionResultsMarkdown,
-  renderImportLoopProfileMarkdown,
-  renderPlatformProbesMarkdown,
-  renderProfileDiffMarkdown,
-  renderRefDiffMarkdown,
-  renderRuntimeProfileMarkdown,
-  renderRuntimeCaptureMarkdown,
-  renderWorkspacePlanMarkdown,
-  renderMarkdownReport,
-  validateCiPolicyReport,
-  validateContractCoverage,
-  writeCiSummary,
-  writeCiPolicyReport,
-  writeColdImportReadiness,
-  writeContractCapture,
-  writeExecutionResultsReport,
-  writeImportLoopProfile,
-  writePlatformProbes,
-  writeProfileDiff,
-  writeRefDiff,
-  writeRuntimeProfile,
-  writeRuntimeCaptureReport,
-  writeWorkspacePlan,
-  writeReport,
-} from "@openclaw/plugin-inspector";
-
-const config = await loadInspectorConfig("crabpot.config.json");
-const report = await inspectFixtureSet(config);
-await writeReport(report, { outDir: "reports" });
-
-const summary = await buildCiSummary({ reportsDir: "reports" });
-await writeCiSummary(summary);
-
-const policyReport = buildCiPolicyReport({ policy, compatibilityReport: report });
-await writeCiPolicyReport(policyReport);
-
-const capture = buildContractCapture({ report });
-await writeContractCapture(capture);
-const coverageErrors = validateContractCoverage(report);
-
-const readiness = buildColdImportReadiness({ report });
-await writeColdImportReadiness(readiness);
-
-const target = await readOpenClawTargetSurface({ manifest: config });
-
-const workspacePlan = await buildWorkspacePlan({ report, readiness });
-await writeWorkspacePlan(workspacePlan);
-
-const platformProbes = buildPlatformProbes({ plan: workspacePlan });
-await writePlatformProbes(platformProbes);
-
-const executionResults = await buildExecutionResultsReport({ resultsDir: ".plugin-inspector/results" });
-await writeExecutionResultsReport(executionResults);
-
-const importLoop = await buildImportLoopProfile({ entrypoint: "dist/index.js", runs: 3 });
-await writeImportLoopProfile(importLoop);
-
-const runtimeProfile = await buildRuntimeProfile({
-  commands: [{ id: "node-boot", label: "Node boot", category: "baseline", args: ["-e", "0"] }],
-});
-await writeRuntimeProfile(runtimeProfile);
-
-const runtimeCapture = await buildRuntimeCaptureReport({ report, rootDir: process.cwd() });
-await writeRuntimeCaptureReport(runtimeCapture);
-
-const refDiff = await buildRefDiff({ baseReport, headReport });
-await writeRefDiff(refDiff);
-
-const profileDiff = await buildProfileDiff({ current, baseline, policy });
-await writeProfileDiff(profileDiff);
-```
-
 ## Scope
 
 Default inspection is offline and credential-free. It reads manifests, package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",
@@ -22,6 +22,7 @@
   },
   "exports": {
     ".": "./src/index.js",
+    "./advanced": "./src/advanced.js",
     "./capture-api": "./src/capture-api.js",
     "./ci-policy": "./src/ci-policy.js",
     "./cold-import-readiness": "./src/cold-import-readiness.js",
@@ -45,7 +46,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "check": "npm test && npm pack --dry-run && npm publish --dry-run --access public",
+    "check": "npm test && npm pack --dry-run",
     "release:local": "npm run check",
     "test": "node --test test/*.test.js"
   },

package/src/advanced.js

@@ -0,0 +1,186 @@
+export {
+  escapeMarkdownTableCell,
+  renderArtifactContent,
+  renderMarkdownTable,
+  renderPaddedMarkdownTable,
+  writeArtifacts,
+  writeJsonMarkdownArtifacts,
+} from "./artifacts.js";
+export {
+  normalizeRepoPath,
+  posixJoin,
+  resolveFromRoot,
+  resolveRequiredFromRoot,
+  slugForArtifact,
+  toRepoPath,
+} from "./path-utils.js";
+export { readJsonFile, readOptionalJsonFile } from "./json-file.js";
+export { assertRunCount, percentile } from "./stats.js";
+export { createCaptureApi } from "./capture-api.js";
+export {
+  buildCiPolicyReport,
+  defaultCiPolicyReportOptions,
+  renderCiPolicyMarkdown,
+  validateCiPolicy,
+  validateCiPolicyReport,
+  writeCiPolicyReport,
+} from "./ci-policy.js";
+export {
+  buildCiSummary,
+  defaultCiReportPaths,
+  deriveCiStatus,
+  readCiReports,
+  renderCiSummaryMarkdown,
+  writeCiSummary,
+} from "./ci-summary.js";
+export {
+  buildContractProbes,
+  contractProbeRules,
+  probePriority,
+} from "./contract-probes.js";
+export {
+  buildContractCapture,
+  defaultHookAssertions,
+  defaultHookContexts,
+  defaultHookEvents,
+  defaultRegistrationArguments,
+  defaultRegistrationAssertions,
+  renderContractCaptureMarkdown,
+  validateContractCapture,
+  writeContractCapture,
+} from "./contract-capture.js";
+export {
+  renderCompatibilityIssuesReport,
+  renderCompatibilityMarkdownReport,
+} from "./compatibility-report.js";
+export {
+  knownIssueClasses,
+  validateContractCoverage,
+} from "./contract-coverage.js";
+export {
+  buildColdImportReadiness,
+  renderColdImportReadinessMarkdown,
+  validateColdImportReadiness,
+  writeColdImportReadiness,
+} from "./cold-import-readiness.js";
+export {
+  buildIssues,
+  classifyIssueFinding,
+  deprecatedCompatRecords,
+  issueId,
+  issueMetadata,
+  issueMetadataByCode,
+  knownIssueCodes,
+  summarizeIssueClasses,
+} from "./issues.js";
+export {
+  buildExecutionResultsReport,
+  defaultExecutionResultsOptions,
+  renderExecutionResultsMarkdown,
+  writeExecutionResultsReport,
+} from "./execution-results.js";
+export {
+  buildCompatibilityFixtureReport,
+  classifyCompatibilityFixture,
+  classifyPackageContracts,
+  classifyTargetOpenClawCoverage,
+  readPackageSummaries,
+  readPluginManifests,
+  summarizePackage,
+} from "./fixture-summary.js";
+export {
+  buildImportLoopProfile,
+  defaultImportLoopProfileOptions,
+  renderImportLoopProfileMarkdown,
+  validateImportLoopProfile,
+  writeImportLoopProfile,
+} from "./import-loop-profile.js";
+export {
+  defaultOpenClawCheckoutPaths,
+  openClawTargetPathCandidates,
+  parseCompatRecordEntries,
+  parseExportedStringArray,
+  parsePluginSdkExports,
+  parseTypeFields,
+  readOpenClawTargetSurface,
+} from "./openclaw-target.js";
+export {
+  captureEntrypoint,
+  captureEntrypointWithMockSdk,
+  inspectCompatibilityFixtureSet,
+  inspectFixtureSet,
+  inspectPlugin,
+  inspectSourceText,
+} from "./inspector.js";
+export {
+  defaultPluginRootConfigFiles,
+  fixtureCheckoutPath,
+  fixtureSourceRoot,
+  loadInspectorConfig,
+  loadPluginRootConfig,
+  normalizeInspectorConfig,
+  normalizePluginRootConfig,
+  validateInspectorConfig,
+} from "./config.js";
+export {
+  buildPlatformProbes,
+  defaultPlatformTargets,
+  renderPlatformProbesMarkdown,
+  validatePlatformProbes,
+  writePlatformProbes,
+} from "./platform-probes.js";
+export {
+  buildProfileDiff,
+  defaultProfileDiffOptions,
+  renderProfileDiffMarkdown,
+  validateProfileDiff,
+  writeProfileDiff,
+} from "./profile-diff.js";
+export {
+  buildRefDiff,
+  defaultRefDiffDimensions,
+  defaultRefDiffOptions,
+  renderRefDiffMarkdown,
+  validateRefDiff,
+  writeRefDiff,
+} from "./ref-diff.js";
+export {
+  buildCompatibilityReport,
+  classifyCompatRecordCoverage,
+  renderMarkdownReport,
+  renderTextSummary,
+  writeCompatibilityReport,
+  writeReport,
+} from "./report.js";
+export {
+  buildRuntimeProfile,
+  defaultRuntimeProfileCommands,
+  defaultRuntimeProfileOptions,
+  renderRuntimeProfileMarkdown,
+  validateRuntimeProfile,
+  writeRuntimeProfile,
+} from "./runtime-profile.js";
+export {
+  buildRuntimeCaptureReport,
+  renderRuntimeCaptureMarkdown,
+  writeRuntimeCaptureReport,
+} from "./runtime-capture-report.js";
+export { createMockSdkPackage } from "./sdk-mock.js";
+export {
+  buildSyntheticProbePlan,
+  defaultSyntheticHookContexts,
+  defaultSyntheticHookEvents,
+  defaultSyntheticRegistrationArguments,
+  renderSyntheticProbeMarkdown,
+  runCapturedSyntheticProbes,
+  syntheticRegistrationExecutionProfiles,
+  validateSyntheticProbePlan,
+  writeSyntheticProbePlan,
+} from "./synthetic-probes.js";
+export {
+  buildWorkspacePlan,
+  defaultWorkspacePlanOptions,
+  renderWorkspacePlanMarkdown,
+  validateWorkspacePlan,
+  writeWorkspacePlan,
+} from "./workspace-plan.js";

package/src/api.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { createCaptureApi } from "./capture-api.js";
+import { loadInspectorConfig, loadPluginRootConfig } from "./config.js";
+import { captureEntrypoint } from "./inspector.js";
+import { renderTextSummary, writeCompatibilityReport } from "./report.js";
+import { buildRuntimeCaptureReport, writeRuntimeCaptureReport } from "./runtime-capture-report.js";
+import { inspectCompatibilityFixtureSet, inspectFixtureSet } from "./inspector.js";
+
+export async function loadPluginConfig(options = {}) {
+  if (options.config) {
+    return options.config;
+  }
+  const cwd = options.pluginRoot ?? options.cwd;
+  if (options.configPath) {
+    return options.fixtureSet === true
+      ? loadInspectorConfig(options.configPath, { cwd })
+      : loadPluginRootConfig(options.configPath, { cwd });
+  }
+  return loadPluginRootConfig(null, { cwd });
+}
+
+export async function inspectPluginRoot(options = {}) {
+  const config = await loadPluginConfig(options);
+  return inspectCompatibilityFixtureSet(config, {
+    generatedAt: options.generatedAt,
+    openclawPath: options.openclawPath,
+    targetOpenClaw: options.targetOpenClaw,
+  });
+}
+
+export async function inspectFixtureSetConfig(options = {}) {
+  const config = options.config ?? (await loadInspectorConfig(options.configPath, { cwd: options.cwd }));
+  return inspectFixtureSet(config, { generatedAt: options.generatedAt });
+}
+
+export async function writePluginReports(report, options = {}) {
+  return writeCompatibilityReport(report, {
+    basename: options.basename,
+    check: options.check,
+    cwd: options.cwd ?? options.pluginRoot,
+    issuesBasename: options.issuesBasename,
+    outDir: options.outDir,
+  });
+}
+
+export async function runPluginCheck(options = {}) {
+  const outDir = options.outDir ?? "reports";
+  const report = await inspectPluginRoot(options);
+  const paths = await writePluginReports(report, { ...options, outDir });
+  const result = { report, paths };
+
+  if (options.capture === true) {
+    if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+      throw new Error("runtime capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+    }
+    const config = await loadPluginConfig(options);
+    const runtimeCapture = await buildRuntimeCaptureReport({
+      mockSdk: options.mockSdk ?? true,
+      report,
+      rootDir: config.rootDir,
+    });
+    const outputRoot = options.cwd ?? options.pluginRoot ?? process.cwd();
+    const runtimeCapturePaths = await writeRuntimeCaptureReport(runtimeCapture, {
+      jsonPath: path.resolve(outputRoot, outDir, "plugin-inspector-runtime-capture.json"),
+      markdownPath: path.resolve(outputRoot, outDir, "plugin-inspector-runtime-capture.md"),
+    });
+    result.runtimeCapture = runtimeCapture;
+    result.runtimeCapturePaths = runtimeCapturePaths;
+    if (runtimeCapture.summary.failedCount > 0) {
+      throw new Error(`plugin-inspector runtime capture failed for ${runtimeCapture.summary.failedCount} entrypoints`);
+    }
+  }
+
+  if (options.failOnBreakages === true && report.status !== "pass") {
+    throw new Error(`plugin-inspector found ${report.summary.breakageCount} breakages`);
+  }
+
+  return result;
+}
+
+export async function capturePluginEntrypoint(entrypoint, options = {}) {
+  return captureEntrypoint(entrypoint, options);
+}
+
+export { createCaptureApi, renderTextSummary };

package/src/cli.js

@@ -1,17 +1,15 @@
 #!/usr/bin/env node
 import {
-  buildRuntimeCaptureReport,
+  renderTextSummary,
+  runPluginCheck,
+} from "./index.js";
+import {
   captureEntrypoint,
-  inspectCompatibilityFixtureSet,
   inspectFixtureSet,
   loadInspectorConfig,
-  loadPluginRootConfig,
-  renderTextSummary,
   writeArtifacts,
-  writeCompatibilityReport,
   writeReport,
-  writeRuntimeCaptureReport,
-} from "./index.js";
+} from "./advanced.js";
 
 const args = process.argv.slice(2);
 const command = args[0]?.startsWith("-") ? "check" : (args[0] ?? "check");
@@ -40,22 +38,7 @@ async function runCheck(commandArgs) {
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
   const json = commandArgs.includes("--json");
   const capture = commandArgs.includes("--capture");
-  const config = configPath ? await loadInspectorConfig(configPath) : await loadPluginRootConfig();
-  const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
-  await writeCompatibilityReport(report, { outDir });
-  if (capture) {
-    if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
-      throw new Error("check --capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
-    }
-    const captureReport = await buildRuntimeCaptureReport({ report, rootDir: config.rootDir, mockSdk: true });
-    await writeRuntimeCaptureReport(captureReport, {
-      jsonPath: `${outDir}/plugin-inspector-runtime-capture.json`,
-      markdownPath: `${outDir}/plugin-inspector-runtime-capture.md`,
-    });
-    if (captureReport.summary.failedCount > 0) {
-      throw new Error(`plugin-inspector runtime capture failed for ${captureReport.summary.failedCount} entrypoints`);
-    }
-  }
+  const { report } = await runPluginCheck({ configPath, outDir, openclawPath, capture });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));

package/src/index.js

@@ -1,186 +1,10 @@
 export {
-  escapeMarkdownTableCell,
-  renderArtifactContent,
-  renderMarkdownTable,
-  renderPaddedMarkdownTable,
-  writeArtifacts,
-  writeJsonMarkdownArtifacts,
-} from "./artifacts.js";
-export {
-  normalizeRepoPath,
-  posixJoin,
-  resolveFromRoot,
-  resolveRequiredFromRoot,
-  slugForArtifact,
-  toRepoPath,
-} from "./path-utils.js";
-export { readJsonFile, readOptionalJsonFile } from "./json-file.js";
-export { assertRunCount, percentile } from "./stats.js";
-export { createCaptureApi } from "./capture-api.js";
-export {
-  buildCiPolicyReport,
-  defaultCiPolicyReportOptions,
-  renderCiPolicyMarkdown,
-  validateCiPolicy,
-  validateCiPolicyReport,
-  writeCiPolicyReport,
-} from "./ci-policy.js";
-export {
-  buildCiSummary,
-  defaultCiReportPaths,
-  deriveCiStatus,
-  readCiReports,
-  renderCiSummaryMarkdown,
-  writeCiSummary,
-} from "./ci-summary.js";
-export {
-  buildContractProbes,
-  contractProbeRules,
-  probePriority,
-} from "./contract-probes.js";
-export {
-  buildContractCapture,
-  defaultHookAssertions,
-  defaultHookContexts,
-  defaultHookEvents,
-  defaultRegistrationArguments,
-  defaultRegistrationAssertions,
-  renderContractCaptureMarkdown,
-  validateContractCapture,
-  writeContractCapture,
-} from "./contract-capture.js";
-export {
-  renderCompatibilityIssuesReport,
-  renderCompatibilityMarkdownReport,
-} from "./compatibility-report.js";
-export {
-  knownIssueClasses,
-  validateContractCoverage,
-} from "./contract-coverage.js";
-export {
-  buildColdImportReadiness,
-  renderColdImportReadinessMarkdown,
-  validateColdImportReadiness,
-  writeColdImportReadiness,
-} from "./cold-import-readiness.js";
-export {
-  buildIssues,
-  classifyIssueFinding,
-  deprecatedCompatRecords,
-  issueId,
-  issueMetadata,
-  issueMetadataByCode,
-  knownIssueCodes,
-  summarizeIssueClasses,
-} from "./issues.js";
-export {
-  buildExecutionResultsReport,
-  defaultExecutionResultsOptions,
-  renderExecutionResultsMarkdown,
-  writeExecutionResultsReport,
-} from "./execution-results.js";
-export {
-  buildCompatibilityFixtureReport,
-  classifyCompatibilityFixture,
-  classifyPackageContracts,
-  classifyTargetOpenClawCoverage,
-  readPackageSummaries,
-  readPluginManifests,
-  summarizePackage,
-} from "./fixture-summary.js";
-export {
-  buildImportLoopProfile,
-  defaultImportLoopProfileOptions,
-  renderImportLoopProfileMarkdown,
-  validateImportLoopProfile,
-  writeImportLoopProfile,
-} from "./import-loop-profile.js";
-export {
-  defaultOpenClawCheckoutPaths,
-  openClawTargetPathCandidates,
-  parseCompatRecordEntries,
-  parseExportedStringArray,
-  parsePluginSdkExports,
-  parseTypeFields,
-  readOpenClawTargetSurface,
-} from "./openclaw-target.js";
-export {
-  captureEntrypoint,
-  captureEntrypointWithMockSdk,
-  inspectCompatibilityFixtureSet,
-  inspectFixtureSet,
-  inspectPlugin,
-  inspectSourceText,
-} from "./inspector.js";
-export {
-  defaultPluginRootConfigFiles,
-  fixtureCheckoutPath,
-  fixtureSourceRoot,
-  loadInspectorConfig,
-  loadPluginRootConfig,
-  normalizeInspectorConfig,
-  normalizePluginRootConfig,
-  validateInspectorConfig,
-} from "./config.js";
-export {
-  buildPlatformProbes,
-  defaultPlatformTargets,
-  renderPlatformProbesMarkdown,
-  validatePlatformProbes,
-  writePlatformProbes,
-} from "./platform-probes.js";
-export {
-  buildProfileDiff,
-  defaultProfileDiffOptions,
-  renderProfileDiffMarkdown,
-  validateProfileDiff,
-  writeProfileDiff,
-} from "./profile-diff.js";
-export {
-  buildRefDiff,
-  defaultRefDiffDimensions,
-  defaultRefDiffOptions,
-  renderRefDiffMarkdown,
-  validateRefDiff,
-  writeRefDiff,
-} from "./ref-diff.js";
-export {
-  buildCompatibilityReport,
-  classifyCompatRecordCoverage,
-  renderMarkdownReport,
+  capturePluginEntrypoint,
+  createCaptureApi,
+  inspectFixtureSetConfig,
+  inspectPluginRoot,
+  loadPluginConfig,
   renderTextSummary,
-  writeCompatibilityReport,
-  writeReport,
-} from "./report.js";
-export {
-  buildRuntimeProfile,
-  defaultRuntimeProfileCommands,
-  defaultRuntimeProfileOptions,
-  renderRuntimeProfileMarkdown,
-  validateRuntimeProfile,
-  writeRuntimeProfile,
-} from "./runtime-profile.js";
-export {
-  buildRuntimeCaptureReport,
-  renderRuntimeCaptureMarkdown,
-  writeRuntimeCaptureReport,
-} from "./runtime-capture-report.js";
-export { createMockSdkPackage } from "./sdk-mock.js";
-export {
-  buildSyntheticProbePlan,
-  defaultSyntheticHookContexts,
-  defaultSyntheticHookEvents,
-  defaultSyntheticRegistrationArguments,
-  renderSyntheticProbeMarkdown,
-  runCapturedSyntheticProbes,
-  syntheticRegistrationExecutionProfiles,
-  validateSyntheticProbePlan,
-  writeSyntheticProbePlan,
-} from "./synthetic-probes.js";
-export {
-  buildWorkspacePlan,
-  defaultWorkspacePlanOptions,
-  renderWorkspacePlanMarkdown,
-  validateWorkspacePlan,
-  writeWorkspacePlan,
-} from "./workspace-plan.js";
+  runPluginCheck,
+  writePluginReports,
+} from "./api.js";