@openclaw/plugin-inspector 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.1 - 2026-04-27
+
+### Changed
+
+- Refresh npm package docs with the simplified CLI-first README and public API surface cleanup.
+
+## 0.1.0 - 2026-04-27
+
+Initial public package release for `@openclaw/plugin-inspector`.
+
+### 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,152 @@
-# @openclaw/plugin-inspector
+<img src="docs/plugin-inspector-banner.jpg" alt="openclaw plugin inspector banner"/>
 
-Bootstrap placeholder. Use 0.1.0 or newer.
+# 💊 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.
+
+## Install
+
+Install it as a dev dependency in a plugin repo:
+
+```bash
+npm install --save-dev @openclaw/plugin-inspector
+```
+
+Then run it from the plugin root:
+
+```bash
+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-*
+```
+
+## 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,59 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.0.0",
-  "description": "OpenClaw plugin inspector bootstrap placeholder.",
-  "license": "MIT"
+  "version": "0.1.1",
+  "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",
+    "./advanced": "./src/advanced.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",
+    "release:local": "npm run check",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "compatibility",
+    "ci"
+  ]
 }

package/src/advanced.js

@@ -0,0 +1,186 @@
+export {
+  escapeMarkdownTableCell,
+  renderArtifactContent,
+  renderMarkdownTable,
+  renderPaddedMarkdownTable,
+  writeArtifacts,
+  writeJsonMarkdownArtifacts,
+} from "./artifacts.js";
+export {
+  normalizeRepoPath,
+  posixJoin,
+  resolveFromRoot,
+  resolveRequiredFromRoot,
+  slugForArtifact,
+  toRepoPath,
+} from "./path-utils.js";
+export { readJsonFile, readOptionalJsonFile } from "./json-file.js";
+export { assertRunCount, percentile } from "./stats.js";
+export { createCaptureApi } from "./capture-api.js";
+export {
+  buildCiPolicyReport,
+  defaultCiPolicyReportOptions,
+  renderCiPolicyMarkdown,
+  validateCiPolicy,
+  validateCiPolicyReport,
+  writeCiPolicyReport,
+} from "./ci-policy.js";
+export {
+  buildCiSummary,
+  defaultCiReportPaths,
+  deriveCiStatus,
+  readCiReports,
+  renderCiSummaryMarkdown,
+  writeCiSummary,
+} from "./ci-summary.js";
+export {
+  buildContractProbes,
+  contractProbeRules,
+  probePriority,
+} from "./contract-probes.js";
+export {
+  buildContractCapture,
+  defaultHookAssertions,
+  defaultHookContexts,
+  defaultHookEvents,
+  defaultRegistrationArguments,
+  defaultRegistrationAssertions,
+  renderContractCaptureMarkdown,
+  validateContractCapture,
+  writeContractCapture,
+} from "./contract-capture.js";
+export {
+  renderCompatibilityIssuesReport,
+  renderCompatibilityMarkdownReport,
+} from "./compatibility-report.js";
+export {
+  knownIssueClasses,
+  validateContractCoverage,
+} from "./contract-coverage.js";
+export {
+  buildColdImportReadiness,
+  renderColdImportReadinessMarkdown,
+  validateColdImportReadiness,
+  writeColdImportReadiness,
+} from "./cold-import-readiness.js";
+export {
+  buildIssues,
+  classifyIssueFinding,
+  deprecatedCompatRecords,
+  issueId,
+  issueMetadata,
+  issueMetadataByCode,
+  knownIssueCodes,
+  summarizeIssueClasses,
+} from "./issues.js";
+export {
+  buildExecutionResultsReport,
+  defaultExecutionResultsOptions,
+  renderExecutionResultsMarkdown,
+  writeExecutionResultsReport,
+} from "./execution-results.js";
+export {
+  buildCompatibilityFixtureReport,
+  classifyCompatibilityFixture,
+  classifyPackageContracts,
+  classifyTargetOpenClawCoverage,
+  readPackageSummaries,
+  readPluginManifests,
+  summarizePackage,
+} from "./fixture-summary.js";
+export {
+  buildImportLoopProfile,
+  defaultImportLoopProfileOptions,
+  renderImportLoopProfileMarkdown,
+  validateImportLoopProfile,
+  writeImportLoopProfile,
+} from "./import-loop-profile.js";
+export {
+  defaultOpenClawCheckoutPaths,
+  openClawTargetPathCandidates,
+  parseCompatRecordEntries,
+  parseExportedStringArray,
+  parsePluginSdkExports,
+  parseTypeFields,
+  readOpenClawTargetSurface,
+} from "./openclaw-target.js";
+export {
+  captureEntrypoint,
+  captureEntrypointWithMockSdk,
+  inspectCompatibilityFixtureSet,
+  inspectFixtureSet,
+  inspectPlugin,
+  inspectSourceText,
+} from "./inspector.js";
+export {
+  defaultPluginRootConfigFiles,
+  fixtureCheckoutPath,
+  fixtureSourceRoot,
+  loadInspectorConfig,
+  loadPluginRootConfig,
+  normalizeInspectorConfig,
+  normalizePluginRootConfig,
+  validateInspectorConfig,
+} from "./config.js";
+export {
+  buildPlatformProbes,
+  defaultPlatformTargets,
+  renderPlatformProbesMarkdown,
+  validatePlatformProbes,
+  writePlatformProbes,
+} from "./platform-probes.js";
+export {
+  buildProfileDiff,
+  defaultProfileDiffOptions,
+  renderProfileDiffMarkdown,
+  validateProfileDiff,
+  writeProfileDiff,
+} from "./profile-diff.js";
+export {
+  buildRefDiff,
+  defaultRefDiffDimensions,
+  defaultRefDiffOptions,
+  renderRefDiffMarkdown,
+  validateRefDiff,
+  writeRefDiff,
+} from "./ref-diff.js";
+export {
+  buildCompatibilityReport,
+  classifyCompatRecordCoverage,
+  renderMarkdownReport,
+  renderTextSummary,
+  writeCompatibilityReport,
+  writeReport,
+} from "./report.js";
+export {
+  buildRuntimeProfile,
+  defaultRuntimeProfileCommands,
+  defaultRuntimeProfileOptions,
+  renderRuntimeProfileMarkdown,
+  validateRuntimeProfile,
+  writeRuntimeProfile,
+} from "./runtime-profile.js";
+export {
+  buildRuntimeCaptureReport,
+  renderRuntimeCaptureMarkdown,
+  writeRuntimeCaptureReport,
+} from "./runtime-capture-report.js";
+export { createMockSdkPackage } from "./sdk-mock.js";
+export {
+  buildSyntheticProbePlan,
+  defaultSyntheticHookContexts,
+  defaultSyntheticHookEvents,
+  defaultSyntheticRegistrationArguments,
+  renderSyntheticProbeMarkdown,
+  runCapturedSyntheticProbes,
+  syntheticRegistrationExecutionProfiles,
+  validateSyntheticProbePlan,
+  writeSyntheticProbePlan,
+} from "./synthetic-probes.js";
+export {
+  buildWorkspacePlan,
+  defaultWorkspacePlanOptions,
+  renderWorkspacePlanMarkdown,
+  validateWorkspacePlan,
+  writeWorkspacePlan,
+} from "./workspace-plan.js";

package/src/api.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { createCaptureApi } from "./capture-api.js";
+import { loadInspectorConfig, loadPluginRootConfig } from "./config.js";
+import { captureEntrypoint } from "./inspector.js";
+import { renderTextSummary, writeCompatibilityReport } from "./report.js";
+import { buildRuntimeCaptureReport, writeRuntimeCaptureReport } from "./runtime-capture-report.js";
+import { inspectCompatibilityFixtureSet, inspectFixtureSet } from "./inspector.js";
+
+export async function loadPluginConfig(options = {}) {
+  if (options.config) {
+    return options.config;
+  }
+  const cwd = options.pluginRoot ?? options.cwd;
+  if (options.configPath) {
+    return options.fixtureSet === true
+      ? loadInspectorConfig(options.configPath, { cwd })
+      : loadPluginRootConfig(options.configPath, { cwd });
+  }
+  return loadPluginRootConfig(null, { cwd });
+}
+
+export async function inspectPluginRoot(options = {}) {
+  const config = await loadPluginConfig(options);
+  return inspectCompatibilityFixtureSet(config, {
+    generatedAt: options.generatedAt,
+    openclawPath: options.openclawPath,
+    targetOpenClaw: options.targetOpenClaw,
+  });
+}
+
+export async function inspectFixtureSetConfig(options = {}) {
+  const config = options.config ?? (await loadInspectorConfig(options.configPath, { cwd: options.cwd }));
+  return inspectFixtureSet(config, { generatedAt: options.generatedAt });
+}
+
+export async function writePluginReports(report, options = {}) {
+  return writeCompatibilityReport(report, {
+    basename: options.basename,
+    check: options.check,
+    cwd: options.cwd ?? options.pluginRoot,
+    issuesBasename: options.issuesBasename,
+    outDir: options.outDir,
+  });
+}
+
+export async function runPluginCheck(options = {}) {
+  const outDir = options.outDir ?? "reports";
+  const report = await inspectPluginRoot(options);
+  const paths = await writePluginReports(report, { ...options, outDir });
+  const result = { report, paths };
+
+  if (options.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,
+      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"),
+    });
+    result.runtimeCapture = runtimeCapture;
+    result.runtimeCapturePaths = runtimeCapturePaths;
+    if (runtimeCapture.summary.failedCount > 0) {
+      throw new Error(`plugin-inspector runtime capture failed for ${runtimeCapture.summary.failedCount} entrypoints`);
+    }
+  }
+
+  if (options.failOnBreakages === true && report.status !== "pass") {
+    throw new Error(`plugin-inspector found ${report.summary.breakageCount} breakages`);
+  }
+
+  return result;
+}
+
+export async function capturePluginEntrypoint(entrypoint, options = {}) {
+  return captureEntrypoint(entrypoint, options);
+}
+
+export { createCaptureApi, renderTextSummary };

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;
+  }
+}