@openclaw/plugin-inspector 0.0.0 → 0.1.0

package/src/ci-policy.js

@@ -0,0 +1,259 @@
+import path from "node:path";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { resolveFromRoot } from "./path-utils.js";
+
+export const defaultCiPolicyReportOptions = {
+  generatedAt: "deterministic",
+  jsonPath: "reports/plugin-inspector-ci-policy.json",
+  markdownPath: "reports/plugin-inspector-ci-policy.md",
+  reportTitle: "Plugin Inspector CI Policy",
+};
+
+export function buildCiPolicyReport(options = {}) {
+  const policy = options.policy;
+  validateCiPolicy(policy);
+
+  const checks = [
+    ...compatibilityChecks(options.compatibilityReport, { strict: options.strict }),
+    ...refDiffChecks(options.refDiff, { strict: options.strict }),
+    ...executionChecks(options.executionResults, policy, { strict: options.strict }),
+  ].sort((left, right) => actionRank(left.action) - actionRank(right.action) || left.id.localeCompare(right.id));
+
+  return {
+    generatedAt: options.generatedAt ?? defaultCiPolicyReportOptions.generatedAt,
+    status: checks.some((check) => check.action === "fail") ? "fail" : "pass",
+    strict: Boolean(options.strict),
+    policy: {
+      allowedBlocked: policy.allowedBlocked.length,
+      expectedWarnings: policy.expectedWarnings.length,
+      fixtureSets: Object.keys(policy.fixtureSets).sort(),
+      thresholds: policy.thresholds,
+    },
+    summary: {
+      checkCount: checks.length,
+      failCount: checks.filter((check) => check.action === "fail").length,
+      warnCount: checks.filter((check) => check.action === "warn").length,
+      passCount: checks.filter((check) => check.action === "pass").length,
+    },
+    checks,
+  };
+}
+
+export function validateCiPolicy(policy) {
+  const errors = [];
+  if (policy?.version !== 1) {
+    errors.push("ci policy version must be 1");
+  }
+  for (const key of ["allowedBlocked", "expectedWarnings"]) {
+    if (!Array.isArray(policy?.[key])) {
+      errors.push(`ci policy ${key} must be an array`);
+    }
+  }
+  if (!policy?.thresholds || typeof policy.thresholds !== "object") {
+    errors.push("ci policy thresholds are required");
+  }
+  if (!policy?.fixtureSets || typeof policy.fixtureSets !== "object") {
+    errors.push("ci policy fixtureSets are required");
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
+
+export function validateCiPolicyReport(report) {
+  return report.checks
+    .filter((check) => check.action === "fail")
+    .map((check) => `${check.id}: ${check.message}: ${check.evidence.join(", ")}`);
+}
+
+export async function writeCiPolicyReport(report, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const jsonPath = resolveFromRoot(rootDir, options.jsonPath ?? defaultCiPolicyReportOptions.jsonPath);
+  const markdownPath = resolveFromRoot(rootDir, options.markdownPath ?? defaultCiPolicyReportOptions.markdownPath);
+  return writeJsonMarkdownArtifacts({
+    jsonPath,
+    markdownPath,
+    json: report,
+    markdown: renderCiPolicyMarkdown(report, options),
+    check: options.check,
+  });
+}
+
+export function renderCiPolicyMarkdown(report, options = {}) {
+  const title = options.title ?? options.reportTitle ?? defaultCiPolicyReportOptions.reportTitle;
+  return [
+    `# ${title}`,
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Status: ${report.status.toUpperCase()}`,
+    `Strict: ${report.strict}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(
+      [
+        ["Checks", report.summary.checkCount],
+        ["Fail", report.summary.failCount],
+        ["Warn", report.summary.warnCount],
+        ["Pass", report.summary.passCount],
+        ["Allowed blocked rules", report.policy.allowedBlocked],
+        ["Expected warning rules", report.policy.expectedWarnings],
+        ["Fixture sets", report.policy.fixtureSets.join(", ")],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Checks",
+    "",
+    markdownTable(
+      report.checks.map((check) => [
+        check.action,
+        check.id,
+        check.message,
+        check.evidence.join(", ") || "-",
+      ]),
+      ["Action", "ID", "Message", "Evidence"],
+    ),
+  ].join("\n");
+}
+
+function compatibilityChecks(report, options) {
+  const checks = [];
+  if (!report) {
+    checks.push({
+      id: "compatibility-report.missing",
+      action: "fail",
+      message: "compatibility report is missing",
+      evidence: [],
+    });
+    return checks;
+  }
+  checks.push({
+    id: "compatibility-report.breakages",
+    action: report.summary.breakageCount > 0 ? "fail" : "pass",
+    message: `${report.summary.breakageCount} hard breakages`,
+    evidence: (report.breakages ?? []).map((finding) => `${finding.fixture}:${finding.code}`),
+  });
+  checks.push({
+    id: "compatibility-report.p1-issues",
+    action: "pass",
+    message: `${report.summary.p1IssueCount} P1 issues tracked`,
+    evidence: (report.issues ?? [])
+      .filter((issue) => issue.severity === "P1")
+      .map((issue) => `${issue.fixture}:${issue.code}`),
+  });
+  const issues = report.issues ?? [];
+  const liveP0Issues = issues.filter((issue) => issue.issueClass === "live-issue" && issue.severity === "P0");
+  const deprecationWarnings = issues.filter((issue) => issue.issueClass === "deprecation-warning");
+  const inspectorGaps = issues.filter((issue) => issue.issueClass === "inspector-gap");
+  checks.push({
+    id: "compatibility-report.live-p0-issues",
+    action: liveP0Issues.length > 0 ? (options.strict ? "fail" : "warn") : "pass",
+    message: `${liveP0Issues.length} live P0 issues tracked`,
+    evidence: liveP0Issues.map((issue) => `${issue.fixture}:${issue.code}:${issue.compatStatus ?? "none"}`),
+  });
+  checks.push({
+    id: "compatibility-report.deprecation-warnings",
+    action: "pass",
+    message: `${deprecationWarnings.length} deprecated compat seams tracked`,
+    evidence: deprecationWarnings.map((issue) => `${issue.fixture}:${issue.code}`),
+  });
+  checks.push({
+    id: "compatibility-report.inspector-gaps",
+    action: "pass",
+    message: `${inspectorGaps.length} inspector proof gaps tracked`,
+    evidence: inspectorGaps.map((issue) => `${issue.fixture}:${issue.code}`),
+  });
+  return checks;
+}
+
+function refDiffChecks(refDiff, options) {
+  if (!refDiff) {
+    return [
+      {
+        id: "ref-diff.not-run",
+        action: "pass",
+        message: "ref diff artifact was not present for this CI mode",
+        evidence: [],
+      },
+    ];
+  }
+
+  return (refDiff.regressions ?? []).map((regression) => ({
+    id: `ref-diff.${regression.code}`,
+    action: regression.action === "fail" || (options.strict && regression.action === "warn") ? "fail" : "warn",
+    message: regression.message,
+    evidence: regression.evidence ?? [],
+  }));
+}
+
+function executionChecks(executionResults, policy, options) {
+  if (!executionResults) {
+    return [
+      {
+        id: "execution-results.not-run",
+        action: "pass",
+        message: "isolated execution artifact was not present for this CI mode",
+        evidence: [],
+      },
+    ];
+  }
+
+  const checks = [
+    {
+      id: "execution-results.failures",
+      action: executionResults.summary.failCount > 0 ? "fail" : "pass",
+      message: `${executionResults.summary.failCount} failed synthetic probes`,
+      evidence: failedExecutionEvidence(executionResults),
+    },
+    {
+      id: "execution-results.audit-findings",
+      action: executionResults.summary.auditFindingCount > 0 ? "warn" : "pass",
+      message: `${executionResults.summary.auditFindingCount ?? 0} package audit findings`,
+      evidence: executionResults.artifacts
+        .filter((artifact) => artifact.kind === "audit" && artifact.findingCount > 0)
+        .map((artifact) => `${artifact.fixture}:${artifact.findingCount}`),
+    },
+  ];
+
+  const blocked = executionResults.artifacts.flatMap((artifact) =>
+    (artifact.blocked ?? []).map((item) => ({ artifact, item })),
+  );
+  for (const blockedItem of blocked) {
+    const expectedWarning = findPolicyMatch(policy.expectedWarnings, blockedItem.item);
+    const allowedBlocked = findPolicyMatch(policy.allowedBlocked, blockedItem.item);
+    const match = expectedWarning ?? allowedBlocked;
+    checks.push({
+      id: `execution-results.blocked.${blockedItem.artifact.fixture}.${blockedItem.item.seam}.${blockedItem.item.captureIndex}`,
+      action: match ? (options.strict ? "fail" : "warn") : "fail",
+      message: match
+        ? `${match.decision}: ${blockedItem.item.reason}`
+        : `unknown blocked synthetic probe: ${blockedItem.item.reason}`,
+      evidence: [
+        blockedItem.artifact.artifactPath,
+        blockedItem.item.seam,
+        blockedItem.item.reason,
+        match?.id ?? "unclassified",
+      ],
+    });
+  }
+  return checks;
+}
+
+function findPolicyMatch(rules, item) {
+  return rules.find((rule) => item.seam === rule.seam && item.reason?.includes(rule.reasonIncludes));
+}
+
+function failedExecutionEvidence(executionResults) {
+  return executionResults.artifacts.flatMap((artifact) =>
+    (artifact.failures ?? []).map((failure) => `${artifact.fixture}:${failure.seam}:${failure.error}`),
+  );
+}
+
+function actionRank(value) {
+  return { fail: 0, warn: 1, pass: 2 }[value] ?? 3;
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}

package/src/ci-summary.js

@@ -0,0 +1,223 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { readOptionalJsonFile } from "./json-file.js";
+
+export const defaultCiReportPaths = {
+  compatibility: "reports/plugin-inspector-report.json",
+  capture: "reports/plugin-inspector-capture.json",
+  synthetic: "reports/plugin-inspector-synthetic-probes.json",
+  coldImport: "reports/plugin-inspector-cold-import.json",
+  workspace: "reports/plugin-inspector-workspace-plan.json",
+  platform: "reports/plugin-inspector-platform-probes.json",
+  importLoop: "reports/plugin-inspector-import-loop-profile.json",
+  execution: "reports/plugin-inspector-execution-results.json",
+  runtimeProfile: "reports/plugin-inspector-runtime-profile.json",
+  refDiff: "reports/plugin-inspector-ref-diff.json",
+  profileDiff: "reports/plugin-inspector-profile-diff.json",
+  ciPolicy: "reports/plugin-inspector-ci-policy.json",
+};
+
+export async function buildCiSummary(options = {}) {
+  const reportPaths = options.reportPaths ?? defaultCiReportPaths;
+  const reports = options.reports ?? (await readCiReports(options.reportsDir ?? "reports", reportPaths));
+  const artifactBaseDir = options.artifactBaseDir ?? process.cwd();
+
+  return {
+    generatedAt: options.generatedAt ?? "deterministic",
+    title: options.title ?? "Plugin Inspector CI Summary",
+    mode: options.mode ?? "local",
+    openclawLabel: options.openclawLabel ?? "",
+    status: deriveCiStatus(reports),
+    summary: {
+      breakages: reports.compatibility?.summary?.breakageCount ?? 0,
+      warnings: reports.compatibility?.summary?.warningCount ?? 0,
+      suggestions: reports.compatibility?.summary?.suggestionCount ?? 0,
+      issues: reports.compatibility?.summary?.issueCount ?? 0,
+      p0Issues: reports.compatibility?.summary?.p0IssueCount ?? 0,
+      p1Issues: reports.compatibility?.summary?.p1IssueCount ?? 0,
+      liveIssues: reports.compatibility?.summary?.liveIssueCount ?? 0,
+      liveP0Issues: reports.compatibility?.summary?.liveP0IssueCount ?? 0,
+      compatGaps: reports.compatibility?.summary?.compatGapCount ?? 0,
+      deprecationWarnings: reports.compatibility?.summary?.deprecationWarningCount ?? 0,
+      inspectorGaps: reports.compatibility?.summary?.inspectorGapCount ?? 0,
+      upstreamIssues: reports.compatibility?.summary?.upstreamIssueCount ?? 0,
+      refDiffFailures: reports.refDiff?.summary?.hardRegressionCount ?? 0,
+      refDiffWarnings: reports.refDiff?.summary?.warningRegressionCount ?? 0,
+      policyFailures: reports.ciPolicy?.summary?.failCount ?? 0,
+      policyWarnings: reports.ciPolicy?.summary?.warnCount ?? 0,
+      profileFailures: reports.profileDiff?.summary?.failCount ?? 0,
+      profileWarnings: reports.profileDiff?.summary?.warnCount ?? 0,
+      executionPass: reports.execution?.summary?.passCount ?? 0,
+      executionFail: reports.execution?.summary?.failCount ?? 0,
+      executionBlocked: reports.execution?.summary?.blockedCount ?? 0,
+      platformWindowsRisks: reports.platform?.summary?.windowsRiskStepCount ?? 0,
+      platformContainerRisks: reports.platform?.summary?.containerRiskStepCount ?? 0,
+      loaderJitiCandidates: reports.platform?.summary?.jitiAlternativeCount ?? 0,
+      importLoopP50Ms: reports.importLoop?.summary?.p50WallMs ?? 0,
+      importLoopP95Ms: reports.importLoop?.summary?.p95WallMs ?? 0,
+      importLoopMaxRssMb: reports.importLoop?.summary?.maxPeakRssMb ?? 0,
+      importLoopMaxCpuMs: reports.importLoop?.summary?.maxCpuMsEstimate ?? 0,
+    },
+    topIssues: topIssues(reports.compatibility),
+    refRegressions: (reports.refDiff?.regressions ?? []).slice(0, 20),
+    policyFindings: (reports.ciPolicy?.checks ?? []).filter((check) => check.action !== "pass").slice(0, 20),
+    profileFindings: (reports.profileDiff?.checks ?? []).filter((check) => check.action !== "pass").slice(0, 20),
+    artifacts: Object.fromEntries(
+      Object.entries(reportPaths).map(([key, value]) => [key, existsSync(path.join(artifactBaseDir, value)) ? value : null]),
+    ),
+  };
+}
+
+export async function readCiReports(reportsDir, reportPaths = defaultCiReportPaths) {
+  const reports = {};
+  for (const [key, defaultPath] of Object.entries(reportPaths)) {
+    const reportPath = path.join(reportsDir, path.basename(defaultPath));
+    reports[key] = await readOptionalJsonFile(reportPath);
+  }
+  return reports;
+}
+
+export function deriveCiStatus(reports) {
+  if ((reports.compatibility?.summary?.breakageCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.refDiff?.summary?.hardRegressionCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.ciPolicy?.summary?.failCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.profileDiff?.summary?.failCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.execution?.summary?.failCount ?? 0) > 0) {
+    return "fail";
+  }
+  return "pass";
+}
+
+export async function writeCiSummary(summary, options = {}) {
+  const jsonPath = options.jsonPath ?? path.join(process.cwd(), "reports/plugin-inspector-ci-summary.json");
+  const markdownPath = options.markdownPath ?? path.join(process.cwd(), "reports/plugin-inspector-ci-summary.md");
+  return writeJsonMarkdownArtifacts({
+    jsonPath,
+    markdownPath,
+    json: summary,
+    markdown: renderCiSummaryMarkdown(summary),
+    check: options.check,
+  });
+}
+
+export function renderCiSummaryMarkdown(summary) {
+  return [
+    `# ${summary.title ?? "Plugin Inspector CI Summary"}`,
+    "",
+    `Generated: ${summary.generatedAt}`,
+    `Mode: ${summary.mode}`,
+    `OpenClaw: ${summary.openclawLabel || "-"}`,
+    `Status: ${summary.status.toUpperCase()}`,
+    "",
+    "## Counts",
+    "",
+    markdownTable(
+      [
+        ["Breakages", summary.summary.breakages],
+        ["Warnings", summary.summary.warnings],
+        ["Suggestions", summary.summary.suggestions],
+        ["Issues", summary.summary.issues],
+        ["P0 issues", summary.summary.p0Issues],
+        ["P1 issues", summary.summary.p1Issues],
+        ["Live issues", summary.summary.liveIssues],
+        ["Live P0 issues", summary.summary.liveP0Issues],
+        ["Compat gaps", summary.summary.compatGaps],
+        ["Deprecation warnings", summary.summary.deprecationWarnings],
+        ["Inspector gaps", summary.summary.inspectorGaps],
+        ["Upstream metadata", summary.summary.upstreamIssues],
+        ["Ref diff failures", summary.summary.refDiffFailures],
+        ["Ref diff warnings", summary.summary.refDiffWarnings],
+        ["Policy failures", summary.summary.policyFailures],
+        ["Policy warnings", summary.summary.policyWarnings],
+        ["Profile failures", summary.summary.profileFailures],
+        ["Profile warnings", summary.summary.profileWarnings],
+        ["Execution pass", summary.summary.executionPass],
+        ["Execution fail", summary.summary.executionFail],
+        ["Execution blocked", summary.summary.executionBlocked],
+        ["Windows portability risks", summary.summary.platformWindowsRisks],
+        ["Container portability risks", summary.summary.platformContainerRisks],
+        ["Jiti loader candidates", summary.summary.loaderJitiCandidates],
+        [
+          "Import loop",
+          `p50 ${summary.summary.importLoopP50Ms} ms / p95 ${summary.summary.importLoopP95Ms} ms / max RSS ${summary.summary.importLoopMaxRssMb} MB / CPU ${summary.summary.importLoopMaxCpuMs} ms`,
+        ],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Top Issues",
+    "",
+    markdownTable(
+      summary.topIssues.map((issue) => [issue.severity, issue.issueClass ?? "-", issue.fixture, issue.code, issue.decision, issue.title]),
+      ["Severity", "Class", "Fixture", "Code", "Decision", "Title"],
+    ),
+    "",
+    "## Ref Regressions",
+    "",
+    markdownTable(
+      summary.refRegressions.map((regression) => [
+        regression.action,
+        regression.severity,
+        regression.dimension,
+        regression.code,
+        regression.message,
+      ]),
+      ["Action", "Severity", "Surface", "Code", "Message"],
+    ),
+    "",
+    "## Policy Findings",
+    "",
+    markdownTable(
+      summary.policyFindings.map((finding) => [finding.action, finding.id, finding.message, finding.evidence.join(", ")]),
+      ["Action", "ID", "Message", "Evidence"],
+    ),
+    "",
+    "## Profile Findings",
+    "",
+    markdownTable(
+      summary.profileFindings.map((finding) => [
+        finding.action,
+        finding.id,
+        finding.metric,
+        finding.baseline ?? "-",
+        finding.current ?? "-",
+        finding.message,
+      ]),
+      ["Action", "ID", "Metric", "Baseline", "Current", "Message"],
+    ),
+    "",
+    "## Artifacts",
+    "",
+    markdownTable(
+      Object.entries(summary.artifacts).map(([key, value]) => [key, value ?? "-"]),
+      ["Artifact", "Path"],
+    ),
+  ].join("\n");
+}
+
+function topIssues(report) {
+  return (report?.issues ?? [])
+    .filter((issue) => ["P0", "P1"].includes(issue.severity))
+    .slice(0, 20)
+    .map((issue) => ({
+      severity: issue.severity,
+      issueClass: issue.issueClass,
+      fixture: issue.fixture,
+      code: issue.code,
+      title: issue.title,
+      decision: issue.decision,
+    }));
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers, { nullValue: "-" });
+}

package/src/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import {
+  buildRuntimeCaptureReport,
+  captureEntrypoint,
+  inspectCompatibilityFixtureSet,
+  inspectFixtureSet,
+  loadInspectorConfig,
+  loadPluginRootConfig,
+  renderTextSummary,
+  writeArtifacts,
+  writeCompatibilityReport,
+  writeReport,
+  writeRuntimeCaptureReport,
+} from "./index.js";
+
+const args = process.argv.slice(2);
+const command = args[0]?.startsWith("-") ? "check" : (args[0] ?? "check");
+const commandArgs = args[0]?.startsWith("-") ? args : args.slice(1);
+
+try {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+  } else if (command === "check") {
+    await runCheck(commandArgs);
+  } else if (command === "inspect" || command === "report" || command === "ci") {
+    await runReport(command, commandArgs);
+  } else if (command === "capture") {
+    await runCapture(commandArgs);
+  } else {
+    throw new Error(`unknown command: ${command}`);
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+
+async function runCheck(commandArgs) {
+  const configPath = readFlag(commandArgs, "--config");
+  const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const json = commandArgs.includes("--json");
+  const capture = commandArgs.includes("--capture");
+  const config = configPath ? await loadInspectorConfig(configPath) : await loadPluginRootConfig();
+  const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
+  await writeCompatibilityReport(report, { outDir });
+  if (capture) {
+    if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+      throw new Error("check --capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+    }
+    const captureReport = await buildRuntimeCaptureReport({ report, rootDir: config.rootDir, mockSdk: true });
+    await writeRuntimeCaptureReport(captureReport, {
+      jsonPath: `${outDir}/plugin-inspector-runtime-capture.json`,
+      markdownPath: `${outDir}/plugin-inspector-runtime-capture.md`,
+    });
+    if (captureReport.summary.failedCount > 0) {
+      throw new Error(`plugin-inspector runtime capture failed for ${captureReport.summary.failedCount} entrypoints`);
+    }
+  }
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderTextSummary(report));
+  }
+
+  if (report.status !== "pass") {
+    throw new Error(`plugin-inspector found ${report.summary.breakageCount} breakages`);
+  }
+}
+
+async function runReport(command, commandArgs) {
+  const configPath = readFlag(commandArgs, "--config");
+  const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const check = commandArgs.includes("--check") || command === "ci";
+  const json = commandArgs.includes("--json");
+  const config = await loadInspectorConfig(configPath);
+  const report = await inspectFixtureSet(config);
+  await writeReport(report, { outDir });
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderTextSummary(report));
+  }
+
+  if (check && report.status !== "pass") {
+    throw new Error(`plugin-inspector found ${report.summary.breakageCount} breakages`);
+  }
+}
+
+async function runCapture(commandArgs) {
+  const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
+  const outputPath = readFlag(commandArgs, "--output");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root");
+  const mockSdk = commandArgs.includes("--mock-sdk");
+  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 printHelp() {
+  console.log(`plugin-inspector
+
+Usage:
+  plugin-inspector check [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--capture] [--json]
+  plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
+  plugin-inspector inspect --config <path> [--out <dir>] [--check] [--json]
+  plugin-inspector ci --config <path> [--out <dir>]
+  PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture <entrypoint> [--mock-sdk] [--plugin-root <path>] [--output <path>]
+`);
+}