@openclaw/plugin-inspector 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.3 - 2026-04-27
+
+### Added
+
+- Add reserved bundled-plugin SDK import detection so external plugins get explicit compatibility findings for private OpenClaw SDK shims.
+- Add packaged workspace capture and synthetic-probe helper CLIs for generated isolated workspace plans.
+
+### Changed
+
+- Make `plugin-inspector ci` write compatibility-backed CI summary artifacts instead of the legacy inventory report.
+- Default packaged helper captures to the mocked OpenClaw SDK while preserving `--real-sdk` opt-in behavior.
+- Detect the default runtime capture artifact at `reports/plugin-inspector-runtime-capture.json`.
+- Report the actual log count in CLI text summaries.
+
+## 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

package/README.md

@@ -1,36 +1,46 @@
 <img src="docs/plugin-inspector-banner.jpg" alt="openclaw plugin inspector banner"/>
 
-# 💊 OpenClaw Plugin Inspector
+# 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.
+`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
 
-Install it as a dev dependency in a plugin repo:
+From a plugin package directory:
 
 ```bash
-npm install --save-dev @openclaw/plugin-inspector
+npx @openclaw/plugin-inspector
 ```
 
-Then 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
-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`
@@ -43,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
 {
@@ -58,6 +68,9 @@ expected seams:
       "registrations": ["registerTool"]
     }
   },
+  "capture": {
+    "mockSdk": true
+  },
   "openclaw": {
     "defaultCheckoutPath": "../openclaw"
   }
@@ -70,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`:
-
-```bash
-PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --capture
-```
+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.
 
-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:
 
-With a dev dependency:
+```bash
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture ./dist/index.js --mock-sdk
+```
+
+## CI
+
+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
@@ -131,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:
@@ -140,6 +156,31 @@ jobs:
           path: reports/plugin-inspector-*
 ```
 
+## 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
@@ -148,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.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/advanced.js

@@ -100,6 +100,7 @@ export {
   openClawTargetPathCandidates,
   parseCompatRecordEntries,
   parseExportedStringArray,
+  parsePluginSdkEntrypointSpecifiers,
   parsePluginSdkExports,
   parseTypeFields,
   readOpenClawTargetSurface,
@@ -116,12 +117,21 @@ 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,

package/src/api.js

@@ -1,6 +1,7 @@
 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";
@@ -45,24 +46,25 @@ export async function writePluginReports(report, options = {}) {
 
 export async function runPluginCheck(options = {}) {
   const outDir = options.outDir ?? "reports";
-  const report = await inspectPluginRoot(options);
-  const paths = await writePluginReports(report, { ...options, outDir });
+  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 (options.capture === 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 config = await loadPluginConfig(options);
     const runtimeCapture = await buildRuntimeCaptureReport({
-      mockSdk: options.mockSdk ?? true,
+      mockSdk,
       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"),
+      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;
@@ -82,4 +84,8 @@ export async function capturePluginEntrypoint(entrypoint, options = {}) {
   return captureEntrypoint(entrypoint, options);
 }
 
+export async function setupPluginInspector(options = {}) {
+  return writePluginInspectorInit(options);
+}
+
 export { createCaptureApi, renderTextSummary };

package/src/capture-api.js

@@ -1,15 +1,68 @@
+export const defaultCaptureApiRegistrarProfiles = {
+  registerChannel: {
+    returnValue: ({ args }) => registrationObject(args, { id: "channel" }),
+  },
+  registerCli: {
+    returnValue: ({ args }) => registrationObject(args, { name: "cli" }),
+  },
+  registerCommand: {
+    returnValue: ({ args }) => registrationObject(args, { name: "command" }),
+  },
+  registerContextEngine: {
+    returnValue: ({ args }) => registrationObject(args, { id: "context-engine" }),
+  },
+  registerGatewayMethod: {
+    returnValue: ({ args }) => registrationObject(args, { name: "gateway.method" }),
+  },
+  registerHook: {
+    returnValue: ({ api }) => api,
+  },
+  registerHttpRoute: {
+    returnValue: ({ args }) => ({
+      ...registrationObject(args, { method: "GET", path: "/" }),
+      unregister() {},
+    }),
+  },
+  registerInteractiveHandler: {
+    returnValue: ({ args }) => registrationObject(args, { id: "interactive-handler" }),
+  },
+  registerMemoryPromptSection: {
+    returnValue: ({ args }) => registrationObject(args, { id: "memory-prompt-section" }),
+  },
+  registerMemoryRuntime: {
+    returnValue: ({ args }) => registrationObject(args, { id: "memory-runtime" }),
+  },
+  registerProvider: {
+    returnValue: ({ args }) => registrationObject(args, { id: "provider" }),
+  },
+  registerService: {
+    returnValue: ({ args }) => ({
+      ...registrationObject(args, { name: "service" }),
+      start: async () => undefined,
+      stop: async () => undefined,
+    }),
+  },
+  registerSpeechProvider: {
+    returnValue: ({ args }) => registrationObject(args, { id: "speech-provider" }),
+  },
+  registerTool: {
+    returnValue: ({ args }) => registrationObject(args, { name: "tool" }),
+  },
+};
+
 export function createCaptureApi(options = {}) {
   const captured = [];
   const retained = [];
-  const knownRegistrars = new Set(options.knownRegistrars ?? []);
+  const registrarProfiles = {
+    ...defaultCaptureApiRegistrarProfiles,
+    ...(options.registrarProfiles ?? {}),
+  };
+  const knownRegistrars = new Set(options.knownRegistrars ?? Object.keys(registrarProfiles));
   const retainHandlers = options.retainHandlers === true;
 
   const api = new Proxy(
     {
-      config: options.config ?? {},
-      logger: options.logger ?? console,
-      pluginConfig: options.pluginConfig ?? {},
-      runtime: options.runtime ?? {},
+      ...createCaptureContext(options),
       on(name, handler) {
         const captureIndex =
           captured.push({
@@ -42,6 +95,7 @@ export function createCaptureApi(options = {}) {
         }
         if (typeof property === "string" && isRegistrarProperty(property)) {
           return (...args) => {
+            const returnValue = registrationReturnValue(property, args, { api, registrarProfiles });
             const captureIndex =
               captured.push({
                 kind: "registration",
@@ -54,10 +108,11 @@ export function createCaptureApi(options = {}) {
                 kind: "registration",
                 name: property,
                 arguments: args,
+                returnValue,
                 captureIndex,
               });
             }
-            return registrationReturnValue(property, args);
+            return returnValue;
           };
         }
         return undefined;
@@ -68,19 +123,122 @@ export function createCaptureApi(options = {}) {
   return api;
 }
 
+export function createCaptureContext(options = {}) {
+  return {
+    config: options.config ?? {},
+    logger: options.logger ?? console,
+    pluginConfig: options.pluginConfig ?? {},
+    runtime: options.runtime ?? createRuntimeContext(options),
+    secrets: options.secrets ?? createSecretContext(options),
+    store: options.store ?? createStoreContext(options),
+    paths: options.paths ?? {
+      cacheDir: ".plugin-inspector/cache",
+      configDir: ".plugin-inspector/config",
+      dataDir: ".plugin-inspector/data",
+    },
+    agent: options.agent ?? {
+      id: "plugin-inspector-agent",
+      accountId: "default",
+    },
+    gateway: options.gateway ?? {
+      baseUrl: "http://127.0.0.1:0",
+      registerRoute(route) {
+        return {
+          ...route,
+          unregister() {},
+        };
+      },
+    },
+    fetch: options.fetch ?? (async () => ({ ok: true, status: 200, json: async () => ({}), text: async () => "" })),
+  };
+}
+
 function isRegistrarProperty(property) {
   return property.startsWith("register") || property.startsWith("define");
 }
 
-function registrationReturnValue(name, args) {
-  if (name === "registerService") {
+function registrationReturnValue(name, args, context) {
+  const profile = context.registrarProfiles[name];
+  if (profile?.returnValue) {
+    return profile.returnValue({ name, args, api: context.api });
+  }
+  return registrationObject(args, {});
+}
+
+function createRuntimeContext(options) {
+  const runtime = options.runtime ?? {};
+  return {
+    ...runtime,
+    agent: runtime.agent ?? {},
+    env: options.env ?? {},
+    logger: options.logger ?? console,
+    now: () => new Date(0),
+    tts: runtime.tts ?? {},
+    state: {
+      resolveStateDir: () => options.stateDir ?? process.cwd(),
+      ...(runtime.state ?? {}),
+    },
+  };
+}
+
+function createSecretContext(options) {
+  const secrets = new Map(Object.entries(options.secretValues ?? {}));
+  return {
+    async get(name) {
+      return secrets.get(name) ?? null;
+    },
+    async has(name) {
+      return secrets.has(name);
+    },
+    async require(name) {
+      if (!secrets.has(name)) {
+        throw new Error(`Missing mocked secret: ${name}`);
+      }
+      return secrets.get(name);
+    },
+    async resolve(value) {
+      return typeof value === "string" && value.startsWith("secret:") ? (secrets.get(value.slice(7)) ?? null) : value;
+    },
+  };
+}
+
+function createStoreContext() {
+  const values = new Map();
+  return {
+    async delete(key) {
+      return values.delete(key);
+    },
+    async get(key) {
+      return values.get(key);
+    },
+    async list() {
+      return [...values.keys()].sort();
+    },
+    async set(key, value) {
+      values.set(key, value);
+      return value;
+    },
+  };
+}
+
+function registrationObject(args, defaults) {
+  const first = args[0];
+  if (first && typeof first === "object") {
     return {
-      name: objectName(args[0]),
-      start: async () => undefined,
-      stop: async () => undefined,
+      ...defaults,
+      ...first,
+      name: objectName(first) ?? defaults.name,
+      id: objectId(first) ?? defaults.id,
     };
   }
-  return objectName(args[0]) ?? undefined;
+  if (typeof first === "string") {
+    return {
+      ...defaults,
+      name: first,
+      id: defaults.id,
+    };
+  }
+  return { ...defaults };
 }
 
 function summarizeArguments(args) {
@@ -113,3 +271,13 @@ function objectName(value) {
   }
   return typeof value.id === "string" ? value.id : null;
 }
+
+function objectId(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  if (typeof value.id === "string") {
+    return value.id;
+  }
+  return typeof value.name === "string" ? value.name : null;
+}

package/src/capture-cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { captureEntrypoint, writeArtifacts } from "./advanced.js";
+
+const args = process.argv.slice(2);
+
+try {
+  await run(args);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+
+async function run(commandArgs) {
+  const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
+  const outputPath = readFlag(commandArgs, "--output");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? true;
+
+  if (!entrypoint) {
+    throw new Error("capture requires an entrypoint path");
+  }
+  if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+    throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+  }
+
+  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
+  const json = `${JSON.stringify(result, null, 2)}\n`;
+  if (outputPath) {
+    await writeArtifacts([{ path: outputPath, content: json }]);
+  } else {
+    process.stdout.write(json);
+  }
+}
+
+function readFlag(commandArgs, name) {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) {
+    return null;
+  }
+  return commandArgs[index + 1] ?? null;
+}
+
+function readMockSdkFlag(commandArgs) {
+  const sdk = readFlag(commandArgs, "--sdk");
+  if (sdk === "mock") {
+    return true;
+  }
+  if (sdk === "real") {
+    return false;
+  }
+  if (sdk && !["mock", "real"].includes(sdk)) {
+    throw new Error("--sdk must be mock or real");
+  }
+  if (commandArgs.includes("--mock-sdk")) {
+    return true;
+  }
+  if (commandArgs.includes("--real-sdk")) {
+    return false;
+  }
+  return undefined;
+}

package/src/ci-summary.js

@@ -5,7 +5,7 @@ import { readOptionalJsonFile } from "./json-file.js";
 
 export const defaultCiReportPaths = {
   compatibility: "reports/plugin-inspector-report.json",
-  capture: "reports/plugin-inspector-capture.json",
+  capture: "reports/plugin-inspector-runtime-capture.json",
   synthetic: "reports/plugin-inspector-synthetic-probes.json",
   coldImport: "reports/plugin-inspector-cold-import.json",
   workspace: "reports/plugin-inspector-workspace-plan.json",