npm - @openclaw/plugin-inspector - Versions diffs - 0.3.1 → 0.3.2 - Mend

@openclaw/plugin-inspector 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,12 @@
 ## Unreleased
+## 0.3.2 - 2026-04-28
+### Fixed
+- Preserve runtime capture bindings for callback-based registrations so captured hooks and registrations can resolve their bound callback metadata.
 ## 0.3.1 - 2026-04-28
 ### Added

package/README.md CHANGED Viewed

@@ -1,51 +1,74 @@
-<img src="docs/plugin-inspector-banner.jpg" alt="openclaw plugin inspector banner"/>
+<img src="docs/plugin-inspector-banner.jpg" alt="OpenClaw Plugin Inspector banner">
 # OpenClaw Plugin Inspector
-`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.
+`@openclaw/plugin-inspector` is the offline compatibility checker for OpenClaw
+plugin packages and plugin fixture suites.
-## Quick Start
+It answers the questions that matter before a plugin reaches users:
-From a plugin package directory:
+- can OpenClaw discover the package metadata and `openclaw.plugin.json`
+  manifest?
+- which hooks, registration calls, manifest contracts, and SDK imports does the
+  plugin use?
+- does the plugin still look compatible without local OpenClaw internals?
+- if CI finds a breakage, which JSON, Markdown, SARIF, JUnit, and summary
+  artifacts should downstream automation read?
+- when a fixture-suite harness such as Crabpot runs many plugins, which findings
+  are hard breakages, known warnings, live issues, deprecations, or inspector
+  proof gaps?
-```bash
-npx @openclaw/plugin-inspector
-```
+The default path is static, offline, and credential-free. Runtime capture exists,
+but it is opt-in because it imports plugin code.
-That runs `check`, writes report artifacts to `reports/`, and exits non-zero
-when compatibility breakages are found.
+## Requirements
-Package-manager equivalents:
+- Node.js 22 or newer.
+- A plugin package root with `package.json`.
+- `openclaw.plugin.json` when the plugin uses the OpenClaw manifest contract.
+- No OpenClaw checkout, credentials, network service, or live provider access for
+  default inspection.
+Pass `--no-openclaw` when CI should not compare against a local OpenClaw
+checkout. If an OpenClaw checkout is supplied with `--openclaw <path>`, the
+inspector only reads public compatibility surfaces such as compat records, SDK
+exports, hook names, manifest fields, and registrar metadata.
+## Quick Start
+Run this from a plugin package root:
 ```bash
-pnpm dlx @openclaw/plugin-inspector
-yarn dlx @openclaw/plugin-inspector
-bunx @openclaw/plugin-inspector
+npx @openclaw/plugin-inspector inspect --no-openclaw
 ```
-Add a local config and GitHub Actions workflow:
+Equivalent one-off runners:
 ```bash
-npx @openclaw/plugin-inspector init --ci
+pnpm dlx @openclaw/plugin-inspector inspect --no-openclaw
+yarn dlx @openclaw/plugin-inspector inspect --no-openclaw
+bunx @openclaw/plugin-inspector inspect --no-openclaw
 ```
-`init --ci` detects `packageManager` and common lockfiles. Pass
-`--package-manager pnpm`, `npm`, `yarn`, or `bun` when you want to override it.
-Add `--scripts` to write `plugin:check` and `plugin:ci` package scripts.
-Use `--dry-run` to preview the files first.
+The command writes:
-Or install it as a dev dependency:
+- `reports/plugin-inspector-report.json`
+- `reports/plugin-inspector-report.md`
+- `reports/plugin-inspector-issues.md`
+It exits non-zero when hard compatibility breakages are found. Warnings,
+suggestions, issue classifications, and logs stay visible in the report without
+necessarily failing the command.
+## Install In A Plugin Repo
+Install the package when you want repeatable local scripts and CI:
 ```bash
 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:
+Add scripts:
 ```json
 {
@@ -56,55 +79,53 @@ the same command:
 }
 ```
-## Commands
+Then run:
 ```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
-npx @openclaw/plugin-inspector init --ci --scripts --dry-run
-npx @openclaw/plugin-inspector init --ci --scripts --dry-run --json
+npm run plugin:check
 ```
-`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:
+The initializer can write the starter config, package scripts, and GitHub
+Actions workflow:
 ```bash
-plugin-inspector inspect --no-openclaw --sarif --junit
+npx @openclaw/plugin-inspector init --ci --scripts --dry-run
+npx @openclaw/plugin-inspector init --ci --scripts
 ```
-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:
+`init` detects `packageManager` and common lockfiles. Override that with
+`--package-manager npm`, `--package-manager pnpm`, `--package-manager yarn`, or
+`--package-manager bun`. Existing files are protected unless you pass `--force`.
-```bash
-plugin-inspector config --json
-```
+## Configuration
-Use `--no-openclaw` when CI should not compare against a local OpenClaw
-checkout:
+Small plugin repos can keep configuration in `package.json`:
-```bash
-plugin-inspector check --no-openclaw
+```json
+{
+  "scripts": {
+    "plugin:check": "plugin-inspector inspect --no-openclaw",
+    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
+  },
+  "pluginInspector": {
+    "version": 1,
+    "plugin": {
+      "id": "weather",
+      "priority": "high",
+      "seams": ["dynamic-tool"],
+      "sourceRoot": "src",
+      "expect": {
+        "registrations": ["registerTool"]
+      }
+    },
+    "capture": {
+      "mockSdk": true
+    }
+  }
+}
 ```
-Use either `plugin-inspector.config.json` or a `package.json`
-`pluginInspector` block when CI needs stable fixture metadata, expected seams,
-or runtime capture defaults:
+Use `plugin-inspector.config.json` for a standalone config file:
 ```json
 {
@@ -127,66 +148,88 @@ or runtime capture defaults:
 }
 ```
-Then run:
+Inspect the resolved config before wiring CI:
 ```bash
-plugin-inspector check --config plugin-inspector.config.json
+plugin-inspector config --json
 ```
-For a single plugin package, the same config can live in `package.json`:
+Copy-ready examples live in:
-```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
-    }
-  }
-}
-```
+- `examples/plugin-inspector.config.json`
+- `examples/package-json-plugin-inspector.json`
+## Commands
-`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`. SARIF/JUnit CI consumption
-examples live alongside them.
+| Command | Purpose |
+| --- | --- |
+| `plugin-inspector` | Default alias for `check`. |
+| `plugin-inspector check` | Script-friendly plugin-root check. |
+| `plugin-inspector inspect` | Plugin-root check unless `--config` is supplied; with `--config`, runs a fixture report. |
+| `plugin-inspector ci` | Compatibility report plus CI summary, SARIF, and JUnit outputs. |
+| `plugin-inspector config` | Print resolved plugin-root config as text or JSON. |
+| `plugin-inspector init` | Write starter config, scripts, and optional GitHub Actions workflow. |
+| `plugin-inspector report` | Run a fixture-suite config with many plugins. |
+| `plugin-inspector capture` | Runtime-capture one entrypoint directly. |
+Common options:
+| Option | Meaning |
+| --- | --- |
+| `--plugin-root <path>` / `--root <path>` | Check a plugin somewhere other than the current directory. |
+| `--config <path>` | Read a standalone config file. Required for fixture-suite `report`. |
+| `--out <dir>` | Write reports somewhere other than `reports/`. |
+| `--openclaw <path>` | Compare against a local OpenClaw checkout. |
+| `--no-openclaw` | Disable OpenClaw checkout comparison. |
+| `--runtime` / `--capture` | Add opt-in runtime registration capture. |
+| `--no-runtime` / `--no-capture` | Disable runtime capture even when config enables it. |
+| `--mock-sdk` / `--sdk mock` | Use generated SDK and external-package mocks for runtime capture. |
+| `--real-sdk` / `--sdk real` | Use installed real SDK dependencies instead of mocks. |
+| `--allow-execute` | Permit commands that import plugin code. |
+| `--json` | Print machine-readable JSON to stdout. |
+| `--sarif [path]` | Write SARIF from `check` or `inspect`; `ci` enables this by default. |
+| `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
+| `--no-sarif` / `--no-junit` | Disable default `ci` outputs. |
+Run the built-in help for the exact CLI surface:
+```bash
+plugin-inspector --help
+```
 ## Runtime Capture
 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:
+what `register(api)` does. Use it when static inspection cannot prove the actual
+registrations made at runtime.
 ```bash
-npx @openclaw/plugin-inspector check --runtime --mock-sdk --allow-execute
+plugin-inspector inspect --no-openclaw --runtime --mock-sdk --allow-execute
 ```
-`--allow-execute` is the explicit guard for modes that import plugin code. The
-older `PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1` environment guard still works for
-custom harnesses.
+`--allow-execute` is the deliberate safety switch. Without it, modes that import
+plugin code fail closed. The older environment guard still works for custom
+harnesses:
+```bash
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector inspect --no-openclaw --runtime --mock-sdk
+```
-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.
+By default, runtime capture uses generated mocks for `openclaw/plugin-sdk`
+subpaths and unresolved external packages discovered in the plugin import graph.
+That keeps compatibility CI offline and credential-free. It does not call live
+services, launch OpenClaw, run provider SDKs, or emulate service lifecycle side
+effects.
+Use `--real-sdk` only when the plugin workspace already has real SDK
+dependencies installed and you intentionally want that path.
 Runtime capture writes:
 - `reports/plugin-inspector-runtime-capture.json`
 - `reports/plugin-inspector-runtime-capture.md`
-You can also capture one entrypoint directly:
+Capture one entrypoint directly:
 ```bash
 plugin-inspector capture ./dist/index.js --mock-sdk --allow-execute
@@ -194,18 +237,10 @@ plugin-inspector capture ./dist/index.js --mock-sdk --allow-execute
 ## CI
-Minimal package scripts:
+`plugin-inspector ci` writes the normal compatibility report plus CI-native
+summary, SARIF, and JUnit artifacts.
-```json
-{
-  "scripts": {
-    "plugin:check": "plugin-inspector inspect --no-openclaw",
-    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
-  }
-}
-```
-GitHub Actions without a local dev dependency:
+Minimal GitHub Actions workflow:
 ```yaml
 name: plugin-inspector
@@ -233,70 +268,214 @@ 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.
+Generated `ci` artifacts:
+- `reports/plugin-inspector-report.json`
+- `reports/plugin-inspector-report.md`
+- `reports/plugin-inspector-issues.md`
+- `reports/plugin-inspector-ci-summary.json`
+- `reports/plugin-inspector-ci-summary.md`
+- `reports/plugin-inspector.sarif`
+- `reports/plugin-inspector.junit.xml`
+CI examples:
+- `examples/github-actions-plugin-inspector.yml`
+- `examples/github-actions-code-scanning.yml`
+- `examples/gitlab-ci-plugin-inspector.yml`
+- `examples/circleci-plugin-inspector.yml`
+## Report Surfaces
+The compatibility report is the primary contract. Preserve field names and
+finding codes because downstream CI and Crabpot reports may consume them.
+Important report sections:
+| Field | Meaning |
+| --- | --- |
+| `status` | `pass` unless hard breakages exist. |
+| `summary` | Counts for fixtures, breakages, warnings, suggestions, issues, issue classes, and contract probes. |
+| `targetOpenClaw` | Status and public compatibility data read from the optional OpenClaw checkout. |
+| `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, and SDK imports. |
+| `breakages` | Blocking compatibility failures. |
+| `warnings` / `suggestions` | Non-blocking compatibility findings. |
+| `issues` | Normalized issue rows with severity and class. |
+| `contractProbes` | Suggested synthetic probes derived from observed contracts. |
+| `logs` | Informational inventory and coverage rows. |
+| `decisions` | Maintainer-facing follow-up or compatibility-policy decisions. |
+Issue classes currently flow through the reports as live issues, compat gaps,
+deprecation warnings, inspector gaps, upstream metadata, and fixture regressions.
+## CI Policy And Shared Reporting Primitives
+`plugin-inspector` owns the shared CI policy and report rendering primitives.
+Fixture-suite harnesses such as Crabpot should call these exports instead of
+reimplementing scoring, summaries, Markdown, SARIF, or JUnit handling.
+The root API exposes grouped helpers:
+```js
+import { ci } from "@openclaw/plugin-inspector";
+const policyReport = ci.buildPolicyReport({
+  policy,
+  compatibilityReport,
+  executionResults,
+  strict: false,
+});
+await ci.writePolicyReport(policyReport);
+```
+CI policy reports default to:
-For GitHub code scanning, use
-`examples/github-actions-code-scanning.yml`; it uploads
-`reports/plugin-inspector.sarif` through CodeQL's SARIF upload action.
+- `reports/plugin-inspector-ci-policy.json`
+- `reports/plugin-inspector-ci-policy.md`
-For CI test-summary UIs, point JUnit ingestion at
-`reports/plugin-inspector.junit.xml`. Copy-ready GitLab and CircleCI examples
-live in `examples/gitlab-ci-plugin-inspector.yml` and
-`examples/circleci-plugin-inspector.yml`.
+A policy must use `version: 1` and define:
+- `allowedBlocked`
+- `expectedWarnings`
+- `thresholds`
+- `fixtureSets`
+Policy scoring fails hard breakages, unknown blocked synthetic probes, hard ref
+diff regressions, failed execution results, strict live P0 issues, and strict
+classified blockers. Non-strict mode keeps classified blocked probes and live P0
+issues visible as warnings.
+CI summary helpers read the known report set from `reports/` and render one
+machine-readable and one Markdown rollup:
+- compatibility
+- runtime capture
+- synthetic probes
+- cold import readiness
+- workspace plan
+- platform probes
+- import-loop profile
+- execution results
+- runtime profile
+- ref diff
+- profile diff
+- CI policy
 ## Fixture Suites
-Fixture-set configs are still supported for crabpot-style compatibility suites:
+Most plugin authors should use the plugin-root workflow. Use fixture suites when
+one repository intentionally checks many plugins or packages, as Crabpot does.
 ```bash
 plugin-inspector report --config crabpot.config.json --out reports
+plugin-inspector report --config crabpot.config.json --out reports --check
+plugin-inspector ci --config crabpot.config.json --out reports --no-openclaw
 ```
-Use fixture suites when one repo wants to inspect many plugins. Use plugin-root
-`check` for normal plugin CI.
+Fixture-suite configs are loaded through the explicit fixture helpers. That keeps
+normal plugin-root configuration simple while still supporting bulk compatibility
+harnesses.
-## Library Use
+## Public API
-Most plugin repos should use the CLI. Harnesses can import grouped root helpers
-when they need to embed the inspector:
+Prefer the CLI for normal plugin repositories. Import the public API when a test
+harness needs to compose workflows directly:
 ```js
-import { pluginRoot, fixtureSuites, contracts, ci } from "@openclaw/plugin-inspector";
+import { pluginRoot } from "@openclaw/plugin-inspector";
-const { report } = await pluginRoot.runCheck({
+const { report, paths } = await pluginRoot.runCheck({
   pluginRoot: process.cwd(),
   openclawPath: false,
+  outDir: "reports",
 });
-const capture = contracts.buildCapture({ report });
-const summary = await ci.buildSummary({ reports: { compatibility: report } });
+console.log(report.status, paths.jsonPath);
 ```
-The root package groups stable workflows as `pluginRoot`, `fixtureSuites`,
-`staticInspection`, `reports`, `contracts`, `ci`, `runtime`, and `synthetic`.
-Named exports remain available for existing automation.
+Stable grouped facades:
+| Facade | Use |
+| --- | --- |
+| `pluginRoot` | Load config, inspect, run checks, capture entrypoints, or set up a plugin repo. |
+| `fixtureSuites` | Load fixture-suite configs, run reports, and build fixture-suite readiness plans. |
+| `staticInspection` | Inspect source text or fixture sets without the compatibility report layer. |
+| `reports` | Render/write reports and classify issue findings. |
+| `contracts` | Build, render, validate, and write contract captures and coverage. |
+| `ci` | Build summaries, policy reports, execution results, SARIF, and JUnit outputs. |
+| `runtime` | Build runtime profiles, profile diffs, ref diffs, and import-loop profiles. |
+| `synthetic` | Build and run synthetic probe plans. |
-## Mocking Model
+Named exports remain available for existing automation. Prefer the grouped
+facades for new code because they show ownership and keep downstream wrappers
+thin.
-Default inspection is static, offline, and credential-free. Runtime capture is
-the only mode that imports plugin code.
+## Development
-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.
+Repository checks are intentionally small and offline:
+```bash
+npm test
+npm run release:contents
+npm run check
+```
+`npm run check` runs the Node test suite and the package-contents guard. The
+contents guard shells through `npm pack --dry-run --json` and verifies the npm
+tarball includes package entrypoints, examples, README assets, and no private
+`test/`, `scripts/`, or `.github/` paths.
+Useful release-prep commands:
+```bash
+npm run release:local
+npm run release:readiness
+npm run release:notes
+npm run release:plan
+npm run release:crabpot -- --crabpot ../crabpot
+```
+`release:readiness` proves the local package and verifies Crabpot follow-through.
+It does not publish.
+Keep this package dependency-light. Do not add runtime dependencies unless they
+remove real complexity. Default checks must stay offline and credential-free.
+## Release Notes
+The package publishes from annotated `v*` tags through GitHub Actions. The
+release workflow runs the test suite, verifies the npm tarball, publishes the
+GitHub release, and publishes the public npm package through npm trusted
+publishing.
+Before tagging a release:
+1. Move `CHANGELOG.md` `Unreleased` notes into a versioned section.
+2. Update `package.json` to the same version.
+3. Update Crabpot's `pluginInspectorRef` to the release commit.
+4. Run `npm run release:readiness`.
+5. Run the Crabpot plugin-inspector smoke commands printed by
+   `npm run release:crabpot -- --crabpot ../crabpot`.
+After npm publish, update Crabpot's package pin and run:
+```bash
+npm run release:crabpot -- --crabpot ../crabpot --published
+```
-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.
+Do not publish npm packages without explicit owner approval.
-## Scope
+## Contribution Notes
-Default inspection is offline and credential-free. It reads manifests, package
-metadata, and source files, then reports observed `api.on(...)`,
-`api.register*`, `define*`, SDK imports, and manifest contracts.
-OpenClaw target checkout parsing is limited to public compatibility registries,
-SDK package exports, manifest types, hooks, and captured registrar metadata.
+There is no `CONTRIBUTING.md` in this repository. Until one exists, use the repo
+scripts above as the local contract and follow these project rules:
-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.
+- preserve stable report field names and finding codes;
+- prefer public OpenClaw plugin contracts over core internals;
+- isolate any OpenClaw source parsing behind explicit helpers;
+- keep runtime execution behind `--allow-execute` or
+  `PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1`;
+- when behavior, entrypoints, release metadata, or the npm package version
+  change, update Crabpot's `@openclaw/plugin-inspector` pin/docs/smoke path and
+  run the Crabpot plugin-inspector smoke before calling the work done.

package/package.json CHANGED Viewed

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

package/src/capture-api.js CHANGED Viewed

@@ -82,6 +82,24 @@ export function createCaptureApi(options = {}) {
         }
         return api;
       },
+      onConversationBindingResolved(handler) {
+        const captureIndex =
+          captured.push({
+            kind: "hook",
+            name: "onConversationBindingResolved",
+            handlerType: typeof handler,
+            arguments: summarizeArguments([handler]),
+          }) - 1;
+        if (retainHandlers) {
+          retained.push({
+            kind: "hook",
+            name: "onConversationBindingResolved",
+            handler,
+            captureIndex,
+          });
+        }
+        return api;
+      },
     },
     {
       get(target, property) {