@openclaw/plugin-inspector 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-04-27
+
+Initial public package release for `@openclaw/plugin-inspector`.
+
+### Added
+
+- Plugin-root `plugin-inspector check` command with optional `plugin-inspector.config.json`.
+- Static OpenClaw plugin compatibility reports, issue reports, and CI policy summaries.
+- Crabpot-compatible fixture-set inspection and report assembly APIs.
+- Target OpenClaw surface parsing for compat registry records, hook names, registrar names, SDK exports, and manifest type fields.
+- Package metadata, manifest, SDK import, hook, registration, runtime-capture, cold-import, synthetic-probe, runtime-profile, ref-diff, and profile-diff report helpers.
+- Optional `PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --capture` runtime registration capture using a temporary mocked `openclaw/plugin-sdk`.
+- Copy-ready config and GitHub Actions examples under `examples/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,250 @@
-# @openclaw/plugin-inspector
+# plugin-inspector
 
-Bootstrap placeholder. Use 0.1.0 or newer.
+`plugin-inspector` is the reusable OpenClaw plugin compatibility inspector. It
+wraps the static inspection, registration capture, and report model prototyped
+in crabpot into an npm-publishable package.
+
+No npm package has been published yet.
+
+## Install
+
+During development, use a local checkout or packed tarball:
+
+```bash
+npm install --save-dev ../plugin-inspector
+npx plugin-inspector check --no-openclaw
+```
+
+After the package is published, plugin repos should install it as a dev
+dependency and run it from the plugin root:
+
+```bash
+npm install --save-dev @openclaw/plugin-inspector
+npx @openclaw/plugin-inspector check
+```
+
+## CLI
+
+Run the default plugin-root check from a plugin package directory:
+
+```bash
+plugin-inspector check
+```
+
+That command reads the current directory as one plugin, inspects package
+metadata, `openclaw.plugin.json`, source imports, `api.on(...)`,
+`api.register*`, and writes:
+
+- `reports/plugin-inspector-report.json`
+- `reports/plugin-inspector-report.md`
+- `reports/plugin-inspector-issues.md`
+
+Use `--no-openclaw` when CI should not compare against a local OpenClaw
+checkout:
+
+```bash
+plugin-inspector check --no-openclaw
+```
+
+Use a simple plugin-root config when you want stable fixture metadata or
+expected seams:
+
+```json
+{
+  "version": 1,
+  "plugin": {
+    "id": "weather",
+    "priority": "high",
+    "seams": ["dynamic-tool"],
+    "sourceRoot": "src",
+    "expect": {
+      "registrations": ["registerTool"]
+    }
+  },
+  "openclaw": {
+    "defaultCheckoutPath": "../openclaw"
+  }
+}
+```
+
+Then run:
+
+```bash
+plugin-inspector check --config plugin-inspector.config.json
+```
+
+Copy-ready examples 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
+```
+
+Capture a plugin entrypoint in an explicitly isolated execution lane:
+
+```bash
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture ./dist/index.js --mock-sdk
+```
+
+Run the optional runtime capture smoke during `check`:
+
+```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:
+
+- `reports/plugin-inspector-runtime-capture.json`
+- `reports/plugin-inspector-runtime-capture.md`
+
+### CI
+
+With a dev dependency:
+
+```json
+{
+  "scripts": {
+    "plugin:check": "plugin-inspector check --no-openclaw",
+    "plugin:check:runtime": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --capture"
+  }
+}
+```
+
+GitHub Actions:
+
+```yaml
+name: plugin-inspector
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run plugin:check
+      - run: npm run plugin:check:runtime
+      - uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: plugin-inspector-reports
+          path: reports/plugin-inspector-*
+```
+
+## API
+
+```js
+import {
+  buildCiSummary,
+  buildCiPolicyReport,
+  buildColdImportReadiness,
+  buildContractCapture,
+  buildExecutionResultsReport,
+  buildImportLoopProfile,
+  buildPlatformProbes,
+  buildProfileDiff,
+  buildRefDiff,
+  buildRuntimeProfile,
+  buildRuntimeCaptureReport,
+  buildWorkspacePlan,
+  createCaptureApi,
+  inspectFixtureSet,
+  loadInspectorConfig,
+  readOpenClawTargetSurface,
+  renderCiPolicyMarkdown,
+  renderColdImportReadinessMarkdown,
+  renderContractCaptureMarkdown,
+  renderExecutionResultsMarkdown,
+  renderImportLoopProfileMarkdown,
+  renderPlatformProbesMarkdown,
+  renderProfileDiffMarkdown,
+  renderRefDiffMarkdown,
+  renderRuntimeProfileMarkdown,
+  renderRuntimeCaptureMarkdown,
+  renderWorkspacePlanMarkdown,
+  renderMarkdownReport,
+  validateCiPolicyReport,
+  validateContractCoverage,
+  writeCiSummary,
+  writeCiPolicyReport,
+  writeColdImportReadiness,
+  writeContractCapture,
+  writeExecutionResultsReport,
+  writeImportLoopProfile,
+  writePlatformProbes,
+  writeProfileDiff,
+  writeRefDiff,
+  writeRuntimeProfile,
+  writeRuntimeCaptureReport,
+  writeWorkspacePlan,
+  writeReport,
+} from "@openclaw/plugin-inspector";
+
+const config = await loadInspectorConfig("crabpot.config.json");
+const report = await inspectFixtureSet(config);
+await writeReport(report, { outDir: "reports" });
+
+const summary = await buildCiSummary({ reportsDir: "reports" });
+await writeCiSummary(summary);
+
+const policyReport = buildCiPolicyReport({ policy, compatibilityReport: report });
+await writeCiPolicyReport(policyReport);
+
+const capture = buildContractCapture({ report });
+await writeContractCapture(capture);
+const coverageErrors = validateContractCoverage(report);
+
+const readiness = buildColdImportReadiness({ report });
+await writeColdImportReadiness(readiness);
+
+const target = await readOpenClawTargetSurface({ manifest: config });
+
+const workspacePlan = await buildWorkspacePlan({ report, readiness });
+await writeWorkspacePlan(workspacePlan);
+
+const platformProbes = buildPlatformProbes({ plan: workspacePlan });
+await writePlatformProbes(platformProbes);
+
+const executionResults = await buildExecutionResultsReport({ resultsDir: ".plugin-inspector/results" });
+await writeExecutionResultsReport(executionResults);
+
+const importLoop = await buildImportLoopProfile({ entrypoint: "dist/index.js", runs: 3 });
+await writeImportLoopProfile(importLoop);
+
+const runtimeProfile = await buildRuntimeProfile({
+  commands: [{ id: "node-boot", label: "Node boot", category: "baseline", args: ["-e", "0"] }],
+});
+await writeRuntimeProfile(runtimeProfile);
+
+const runtimeCapture = await buildRuntimeCaptureReport({ report, rootDir: process.cwd() });
+await writeRuntimeCaptureReport(runtimeCapture);
+
+const refDiff = await buildRefDiff({ baseReport, headReport });
+await writeRefDiff(refDiff);
+
+const profileDiff = await buildProfileDiff({ current, baseline, policy });
+await writeProfileDiff(profileDiff);
+```
+
+## Scope
+
+Default inspection is offline and credential-free. It reads manifests, package
+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.
+
+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.

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

@@ -0,0 +1,24 @@
+name: plugin-inspector
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run plugin:check
+      - run: npm run plugin:check:runtime
+      - uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: plugin-inspector-reports
+          path: reports/plugin-inspector-*

package/examples/plugin-inspector.config.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "plugin": {
+    "id": "weather",
+    "priority": "high",
+    "seams": ["dynamic-tool"],
+    "sourceRoot": "src",
+    "expect": {
+      "registrations": ["registerTool"]
+    }
+  },
+  "openclaw": {
+    "defaultCheckoutPath": "../openclaw"
+  }
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.0.0",
-  "description": "OpenClaw plugin inspector bootstrap placeholder.",
-  "license": "MIT"
+  "version": "0.1.0",
+  "private": false,
+  "description": "Offline compatibility inspector for OpenClaw plugins.",
+  "type": "module",
+  "license": "MIT",
+  "author": "OpenClaw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openclaw/plugin-inspector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openclaw/plugin-inspector/issues"
+  },
+  "homepage": "https://github.com/openclaw/plugin-inspector#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "plugin-inspector": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./capture-api": "./src/capture-api.js",
+    "./ci-policy": "./src/ci-policy.js",
+    "./cold-import-readiness": "./src/cold-import-readiness.js",
+    "./contract-capture": "./src/contract-capture.js",
+    "./contract-coverage": "./src/contract-coverage.js",
+    "./execution-results": "./src/execution-results.js",
+    "./import-loop-profile": "./src/import-loop-profile.js",
+    "./openclaw-target": "./src/openclaw-target.js",
+    "./platform-probes": "./src/platform-probes.js",
+    "./profile-diff": "./src/profile-diff.js",
+    "./ref-diff": "./src/ref-diff.js",
+    "./runtime-capture-report": "./src/runtime-capture-report.js",
+    "./runtime-profile": "./src/runtime-profile.js",
+    "./workspace-plan": "./src/workspace-plan.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "npm test && npm pack --dry-run && npm publish --dry-run --access public",
+    "release:local": "npm run check",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "compatibility",
+    "ci"
+  ]
 }

package/src/artifacts.js

@@ -0,0 +1,113 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function writeArtifacts(artifacts, options = {}) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) {
+    throw new TypeError("writeArtifacts requires at least one artifact");
+  }
+
+  const written = {};
+  for (const artifact of artifacts) {
+    const artifactPath = artifact.path;
+    if (!artifactPath) {
+      throw new TypeError("artifact.path is required");
+    }
+
+    const content = renderArtifactContent(artifact);
+    await mkdir(path.dirname(artifactPath), { recursive: true });
+    await writeFile(artifactPath, content, "utf8");
+
+    if (options.check || artifact.check) {
+      await assertFileMatches(artifactPath, content);
+    }
+
+    if (artifact.name) {
+      written[artifact.name] = artifactPath;
+    }
+  }
+
+  return written;
+}
+
+export async function writeJsonMarkdownArtifacts({ jsonPath, markdownPath, json, markdown, check = false }) {
+  await writeArtifacts(
+    [
+      { name: "jsonPath", path: jsonPath, json },
+      { name: "markdownPath", path: markdownPath, markdown },
+    ],
+    { check },
+  );
+  return { jsonPath, markdownPath };
+}
+
+export function renderArtifactContent(artifact) {
+  if ("content" in artifact) {
+    return String(artifact.content);
+  }
+  if ("json" in artifact) {
+    return `${JSON.stringify(artifact.json, null, 2)}\n`;
+  }
+  if ("markdown" in artifact) {
+    return `${artifact.markdown}\n`;
+  }
+  throw new TypeError("artifact must provide content, json, or markdown");
+}
+
+export function renderMarkdownTable(rows, headers, options = {}) {
+  if (rows.length === 0 && options.empty != null) {
+    return options.empty;
+  }
+
+  const nullValue = options.nullValue ?? "";
+  const escape = options.escape !== false;
+  const normalizedRows = [headers, ...rows].map((row) =>
+    row.map((cell) => {
+      const value = String(cell ?? nullValue);
+      return escape ? escapeMarkdownTableCell(value) : value;
+    }),
+  );
+
+  if (options.padding) {
+    const widths = headers.map((_, columnIndex) =>
+      Math.max(...normalizedRows.map((row) => row[columnIndex].length)),
+    );
+    const renderRow = (row) => `| ${row.map((cell, index) => cell.padEnd(widths[index])).join(" | ")} |`;
+    return [
+      renderRow(normalizedRows[0]),
+      renderRow(widths.map((width) => "-".repeat(width))),
+      ...normalizedRows.slice(1).map(renderRow),
+    ].join("\n");
+  }
+
+  const separator = headers.map(() => options.separator ?? "---");
+  return [normalizedRows[0], separator, ...normalizedRows.slice(1)]
+    .map((row) => `| ${row.join(" | ")} |`)
+    .join("\n");
+}
+
+export function renderPaddedMarkdownTable(rows, headers, options = {}) {
+  return renderMarkdownTable(rows, headers, {
+    empty: "_none_",
+    escape: false,
+    padding: true,
+    ...options,
+  });
+}
+
+export function escapeMarkdownTableCell(value) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, "<br>");
+}
+
+async function assertFileMatches(filePath, expected) {
+  try {
+    const actual = await readFile(filePath, "utf8");
+    if (actual !== expected) {
+      throw new Error(`${filePath} is not up to date`);
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`${filePath} is missing`);
+    }
+    throw error;
+  }
+}

package/src/capture-api.js

@@ -0,0 +1,115 @@
+export function createCaptureApi(options = {}) {
+  const captured = [];
+  const retained = [];
+  const knownRegistrars = new Set(options.knownRegistrars ?? []);
+  const retainHandlers = options.retainHandlers === true;
+
+  const api = new Proxy(
+    {
+      config: options.config ?? {},
+      logger: options.logger ?? console,
+      pluginConfig: options.pluginConfig ?? {},
+      runtime: options.runtime ?? {},
+      on(name, handler) {
+        const captureIndex =
+          captured.push({
+            kind: "hook",
+            name,
+            handlerType: typeof handler,
+            arguments: summarizeArguments([name, handler]),
+          }) - 1;
+        if (retainHandlers) {
+          retained.push({
+            kind: "hook",
+            name,
+            handler,
+            captureIndex,
+          });
+        }
+        return api;
+      },
+    },
+    {
+      get(target, property) {
+        if (property === "getCapturedContracts") {
+          return () => captured.map((entry) => ({ ...entry }));
+        }
+        if (property === "getRetainedContracts") {
+          return () => retained.map((entry) => ({ ...entry }));
+        }
+        if (property in target) {
+          return target[property];
+        }
+        if (typeof property === "string" && isRegistrarProperty(property)) {
+          return (...args) => {
+            const captureIndex =
+              captured.push({
+                kind: "registration",
+                name: property,
+                known: knownRegistrars.size === 0 ? null : knownRegistrars.has(property),
+                arguments: summarizeArguments(args),
+              }) - 1;
+            if (retainHandlers) {
+              retained.push({
+                kind: "registration",
+                name: property,
+                arguments: args,
+                captureIndex,
+              });
+            }
+            return registrationReturnValue(property, args);
+          };
+        }
+        return undefined;
+      },
+    },
+  );
+
+  return api;
+}
+
+function isRegistrarProperty(property) {
+  return property.startsWith("register") || property.startsWith("define");
+}
+
+function registrationReturnValue(name, args) {
+  if (name === "registerService") {
+    return {
+      name: objectName(args[0]),
+      start: async () => undefined,
+      stop: async () => undefined,
+    };
+  }
+  return objectName(args[0]) ?? undefined;
+}
+
+function summarizeArguments(args) {
+  return args.map((arg) => summarizeValue(arg));
+}
+
+function summarizeValue(value) {
+  if (typeof value === "function") {
+    return { type: "function" };
+  }
+  if (Array.isArray(value)) {
+    return { type: "array", length: value.length };
+  }
+  if (value && typeof value === "object") {
+    return {
+      type: "object",
+      keys: Object.keys(value).sort(),
+      name: objectName(value),
+    };
+  }
+  return { type: typeof value, value };
+}
+
+function objectName(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  if (typeof value.name === "string") {
+    return value.name;
+  }
+  return typeof value.id === "string" ? value.id : null;
+}