@openclaw/plugin-inspector 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 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
+
+- 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

@@ -1,90 +1,131 @@
-<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
 
-Add a local config and GitHub Actions workflow:
+- 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.
 
-```bash
-npx @openclaw/plugin-inspector init --ci
-```
+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.
 
-`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.
+## Quick Start
 
-Or install it as a dev dependency:
+Run this from a plugin package root:
 
 ```bash
-npm install --save-dev @openclaw/plugin-inspector
-npx plugin-inspector check
+npx @openclaw/plugin-inspector inspect --no-openclaw
 ```
 
-## Commands
+Equivalent one-off runners:
 
 ```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
+pnpm dlx @openclaw/plugin-inspector inspect --no-openclaw
+yarn dlx @openclaw/plugin-inspector inspect --no-openclaw
+bunx @openclaw/plugin-inspector inspect --no-openclaw
 ```
 
-`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:
+The command writes:
 
 - `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:
+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
-plugin-inspector inspect --no-openclaw --sarif --junit
+npm install --save-dev @openclaw/plugin-inspector
 ```
 
-That also writes:
+Add scripts:
 
-- `reports/plugin-inspector.sarif`
-- `reports/plugin-inspector.junit.xml`
+```json
+{
+  "scripts": {
+    "plugin:check": "plugin-inspector inspect --no-openclaw",
+    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
+  }
+}
+```
 
-`config` prints the resolved plugin root, fixture id, seams, and capture
-settings before CI runs:
+Then run:
 
 ```bash
-plugin-inspector config --json
+npm run plugin:check
 ```
 
-Use `--no-openclaw` when CI should not compare against a local OpenClaw
-checkout:
+The initializer can write the starter config, package scripts, and GitHub
+Actions workflow:
 
 ```bash
-plugin-inspector check --no-openclaw
+npx @openclaw/plugin-inspector init --ci --scripts --dry-run
+npx @openclaw/plugin-inspector init --ci --scripts
+```
+
+`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`.
+
+## Configuration
+
+Small plugin repos can keep configuration in `package.json`:
+
+```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
 {
@@ -107,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:
 
-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 inspect --no-openclaw --runtime --mock-sdk
+```
+
+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
@@ -174,18 +237,10 @@ plugin-inspector capture ./dist/index.js --mock-sdk --allow-execute
 
 ## CI
 
-Minimal package scripts:
-
-```json
-{
-  "scripts": {
-    "plugin:check": "plugin-inspector inspect --no-openclaw",
-    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
-  }
-}
-```
+`plugin-inspector ci` writes the normal compatibility report plus CI-native
+summary, SARIF, and JUnit artifacts.
 
-GitHub Actions without a local dev dependency:
+Minimal GitHub Actions workflow:
 
 ```yaml
 name: plugin-inspector
@@ -213,50 +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:
+
+- `reports/plugin-inspector-ci-policy.json`
+- `reports/plugin-inspector-ci-policy.md`
 
-For GitHub code scanning, use
-`examples/github-actions-code-scanning.yml`; it uploads
-`reports/plugin-inspector.sarif` through CodeQL's SARIF upload action.
+A policy must use `version: 1` and define:
 
-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`.
+- `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
+```
+
+Fixture-suite configs are loaded through the explicit fixture helpers. That keeps
+normal plugin-root configuration simple while still supporting bulk compatibility
+harnesses.
+
+## Public API
+
+Prefer the CLI for normal plugin repositories. Import the public API when a test
+harness needs to compose workflows directly:
+
+```js
+import { pluginRoot } from "@openclaw/plugin-inspector";
+
+const { report, paths } = await pluginRoot.runCheck({
+  pluginRoot: process.cwd(),
+  openclawPath: false,
+  outDir: "reports",
+});
+
+console.log(report.status, paths.jsonPath);
+```
+
+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. |
+
+Named exports remain available for existing automation. Prefer the grouped
+facades for new code because they show ownership and keep downstream wrappers
+thin.
+
+## Development
+
+Repository checks are intentionally small and offline:
+
+```bash
+npm test
+npm run release:contents
+npm run check
 ```
 
-Use fixture suites when one repo wants to inspect many plugins. Use plugin-root
-`check` for normal plugin CI.
+`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:
 
-## Mocking Model
+```bash
+npm run release:local
+npm run release:readiness
+npm run release:notes
+npm run release:plan
+npm run release:crabpot -- --crabpot ../crabpot
+```
 
-Default inspection is static, offline, and credential-free. Runtime capture is
-the only mode that imports plugin code.
+`release:readiness` proves the local package and verifies Crabpot follow-through.
+It does not publish.
 
-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.
+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

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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/capture-api.js

@@ -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) {

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