@openclaw/plugin-inspector 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.2 - 2026-04-27
+
+### Added
+
+- Add public SDK subpath mocks, registrar return profiles, richer lifecycle capture probes, and plugin-root `init`/`--plugin-root` CLI flows.
+
+### Changed
+
+- Harden runtime capture for TypeScript entrypoints, extensionless local imports, mocked external packages, namespace imports, async output capture, and explicit mock/real SDK lanes.
+- Refresh README and CI examples around `npx @openclaw/plugin-inspector check --no-openclaw` and opt-in runtime capture.
+
+## 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,39 +1,46 @@
-# plugin-inspector
+<img src="docs/plugin-inspector-banner.jpg" alt="openclaw plugin inspector banner"/>
 
-`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.
+# OpenClaw Plugin Inspector
 
-No npm package has been published yet.
+`plugin-inspector` is the offline compatibility check for OpenClaw plugins. Run
+it from a plugin root to inspect package metadata, `openclaw.plugin.json`, SDK
+imports, `api.on(...)`, `api.register*`, and optional runtime registration
+capture.
 
-## Install
+## Quick Start
 
-During development, use a local checkout or packed tarball:
+From a plugin package directory:
 
 ```bash
-npm install --save-dev ../plugin-inspector
-npx plugin-inspector check --no-openclaw
+npx @openclaw/plugin-inspector
 ```
 
-After the package is published, plugin repos should install it as a dev
-dependency and run it from the plugin root:
+That runs `check`, writes report artifacts to `reports/`, and exits non-zero
+when compatibility breakages are found.
+
+Add a local config and GitHub Actions workflow:
 
 ```bash
-npm install --save-dev @openclaw/plugin-inspector
-npx @openclaw/plugin-inspector check
+npx @openclaw/plugin-inspector init --ci
 ```
 
-## CLI
+Or install it as a dev dependency:
 
-Run the default plugin-root check from a plugin package directory:
+```bash
+npm install --save-dev @openclaw/plugin-inspector
+npx plugin-inspector check
+```
+
+## Commands
 
 ```bash
-plugin-inspector check
+npx @openclaw/plugin-inspector check
+npx @openclaw/plugin-inspector check --plugin-root ./plugins/weather
+npx @openclaw/plugin-inspector init --ci --package-manager pnpm
 ```
 
-That command reads the current directory as one plugin, inspects package
-metadata, `openclaw.plugin.json`, source imports, `api.on(...)`,
-`api.register*`, and writes:
+`check` reads the current directory as one plugin unless `--plugin-root` is set.
+It writes:
 
 - `reports/plugin-inspector-report.json`
 - `reports/plugin-inspector-report.md`
@@ -46,8 +53,8 @@ checkout:
 plugin-inspector check --no-openclaw
 ```
 
-Use a simple plugin-root config when you want stable fixture metadata or
-expected seams:
+Use `plugin-inspector.config.json` when CI needs stable fixture metadata,
+expected seams, or runtime capture defaults:
 
 ```json
 {
@@ -61,6 +68,9 @@ expected seams:
       "registrations": ["registerTool"]
     }
   },
+  "capture": {
+    "mockSdk": true
+  },
   "openclaw": {
     "defaultCheckoutPath": "../openclaw"
   }
@@ -73,48 +83,51 @@ Then run:
 plugin-inspector check --config plugin-inspector.config.json
 ```
 
-Copy-ready examples live in `examples/plugin-inspector.config.json` and
+`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/github-actions-plugin-inspector.yml`.
 
-Fixture-set configs are still supported for crabpot-style compatibility suites:
-
-```bash
-plugin-inspector report --config crabpot.config.json --out reports
-```
+## Runtime Capture
 
-Capture a plugin entrypoint in an explicitly isolated execution lane:
+Runtime capture imports plugin entrypoints in an isolated subprocess and records
+the registrations made during `register(api)`. It is opt-in because it executes
+plugin code:
 
 ```bash
-PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture ./dist/index.js --mock-sdk
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --runtime --mock-sdk
 ```
 
-Run the optional runtime capture smoke during `check`:
+By default, runtime capture uses a generated mock for `openclaw/plugin-sdk` and
+common external packages so plugin code can load in clean CI without OpenClaw
+installed. Use `--real-sdk` only when the plugin workspace already has real SDK
+dependencies installed and you intentionally want to test that path.
 
-```bash
-PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --capture
-```
-
-Runtime capture creates a temporary mock `openclaw/plugin-sdk` package, imports
-declared OpenClaw package entrypoints, calls their `register(api)` function with
-the capture API, and writes:
+Runtime capture writes:
 
 - `reports/plugin-inspector-runtime-capture.json`
 - `reports/plugin-inspector-runtime-capture.md`
 
-### CI
+You can also capture one entrypoint directly:
+
+```bash
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture ./dist/index.js --mock-sdk
+```
+
+## CI
 
-With a dev dependency:
+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 --capture"
+    "plugin:check:runtime": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --runtime --mock-sdk"
   }
 }
 ```
 
-GitHub Actions:
+GitHub Actions without a local dev dependency:
 
 ```yaml
 name: plugin-inspector
@@ -134,8 +147,8 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
-      - run: npm run plugin:check
-      - run: npm run plugin:check:runtime
+      - run: npx @openclaw/plugin-inspector check --no-openclaw
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --no-openclaw --runtime --mock-sdk
       - uses: actions/upload-artifact@v5
         if: always()
         with:
@@ -143,101 +156,31 @@ 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);
+## Fixture Suites
+
+Fixture-set configs are still supported for crabpot-style compatibility suites:
+
+```bash
+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.
+
+## Mocking Model
+
+Default inspection is static, offline, and credential-free. Runtime capture is
+the only mode that imports plugin code.
+
+When `--mock-sdk` is enabled, the inspector generates temporary modules for
+`openclaw/plugin-sdk` subpaths and unresolved external packages discovered in
+the plugin import graph. The mock SDK captures registrations; it does not call
+network services, launch OpenClaw, run provider SDKs, or emulate service
+lifecycle side effects.
+
+Use the mock lane for plugin compatibility CI. Keep live provider/service tests
+in the plugin repo behind their own credentials and explicit opt-in flags.
+
 ## Scope
 
 Default inspection is offline and credential-free. It reads manifests, package
@@ -246,5 +189,5 @@ metadata, and source files, then reports observed `api.on(...)`,
 OpenClaw target checkout parsing is limited to public compatibility registries,
 SDK package exports, manifest types, hooks, and captured registrar metadata.
 
-Cold import capture and synthetic contract probes are explicit opt-in modes.
-Live lanes will stay credential-gated and must never run in default CI.
+Cold import capture, synthetic contract probes, and runtime capture are explicit
+opt-in modes. Live lanes stay credential-gated and must never run in default CI.

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

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

package/examples/plugin-inspector.config.json

@@ -9,6 +9,9 @@
       "registrations": ["registerTool"]
     }
   },
+  "capture": {
+    "mockSdk": true
+  },
   "openclaw": {
     "defaultCheckoutPath": "../openclaw"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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,195 @@
+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,
+  inferPluginSeams,
+  loadInspectorConfig,
+  loadPluginRootConfig,
+  normalizeInspectorConfig,
+  normalizePluginRootConfig,
+  packageId,
+  validateInspectorConfig,
+} from "./config.js";
+export {
+  buildPluginInspectorConfig,
+  defaultInitConfigPath,
+  defaultInitWorkflowPath,
+  renderGithubActionsWorkflow,
+  writePluginInspectorInit,
+} from "./init.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,91 @@
+import path from "node:path";
+import { createCaptureApi } from "./capture-api.js";
+import { loadInspectorConfig, loadPluginRootConfig } from "./config.js";
+import { writePluginInspectorInit } from "./init.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 config = await loadPluginConfig(options);
+  const report = await inspectPluginRoot({ ...options, config });
+  const paths = await writePluginReports(report, { ...options, pluginRoot: config.rootDir, outDir });
+  const result = { report, paths };
+  const capture = options.capture ?? config.capture?.runtime ?? false;
+  const mockSdk = options.mockSdk ?? config.capture?.mockSdk ?? true;
+
+  if (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 runtimeCapture = await buildRuntimeCaptureReport({
+      mockSdk,
+      report,
+      rootDir: config.rootDir,
+    });
+    const runtimeCapturePaths = await writeRuntimeCaptureReport(runtimeCapture, {
+      jsonPath: path.resolve(config.rootDir, outDir, "plugin-inspector-runtime-capture.json"),
+      markdownPath: path.resolve(config.rootDir, 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 async function setupPluginInspector(options = {}) {
+  return writePluginInspectorInit(options);
+}
+
+export { createCaptureApi, renderTextSummary };