@openclaw/plugin-inspector 0.0.0 → 0.1.1

package/src/platform-probes.js

@@ -0,0 +1,238 @@
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+
+export const defaultPlatformTargets = ["linux", "macos", "windows", "container"];
+
+export function buildPlatformProbes(options = {}) {
+  const plan = options.plan;
+  if (!plan) {
+    throw new TypeError("buildPlatformProbes requires an isolated workspace plan");
+  }
+
+  const targets = options.targets ?? defaultPlatformTargets;
+  const entrypoints = plan.fixtures.flatMap((fixture) =>
+    fixture.entrypoints.map((entrypoint) => summarizeEntrypoint(fixture.id, entrypoint)),
+  );
+  const portabilityFindings = plan.fixtures.flatMap((fixture) =>
+    fixture.entrypoints.flatMap((entrypoint) =>
+      entrypoint.steps
+        .map((step) => summarizeStep(fixture.id, entrypoint, step))
+        .filter((finding) => finding.riskCodes.length > 0),
+    ),
+  );
+
+  return {
+    generatedAt: plan.generatedAt,
+    mode: "plan-only",
+    targets,
+    summary: {
+      fixtureCount: plan.summary.fixtureCount,
+      entrypointCount: entrypoints.length,
+      tsLoaderEntrypointCount: entrypoints.filter((entrypoint) => entrypoint.loaderPrimary === "tsx").length,
+      jitiAlternativeCount: entrypoints.filter((entrypoint) => entrypoint.loaderAlternatives.includes("jiti")).length,
+      lazyImportProbeCount: entrypoints.filter((entrypoint) => entrypoint.capturePlanned && entrypoint.syntheticProbePlanned).length,
+      portabilityFindingCount: portabilityFindings.length,
+      windowsRiskStepCount: portabilityFindings.filter((finding) => finding.platforms.includes("windows")).length,
+      macosRiskStepCount: portabilityFindings.filter((finding) => finding.platforms.includes("macos")).length,
+      linuxRiskStepCount: portabilityFindings.filter((finding) => finding.platforms.includes("linux")).length,
+      containerRiskStepCount: portabilityFindings.filter((finding) => finding.platforms.includes("container")).length,
+    },
+    entrypoints,
+    portabilityFindings,
+    recommendations: buildRecommendations(portabilityFindings, entrypoints),
+  };
+}
+
+export function validatePlatformProbes(report, options = {}) {
+  const targets = options.targets ?? defaultPlatformTargets;
+  const errors = [];
+  if (report.mode !== "plan-only") {
+    errors.push("platform probes must stay plan-only in default checks");
+  }
+  if (!targets.every((target) => report.targets.includes(target))) {
+    errors.push(`platform probes must cover ${targets.join(", ")} targets`);
+  }
+  if (report.summary.tsLoaderEntrypointCount !== report.summary.jitiAlternativeCount) {
+    errors.push("all TypeScript loader entrypoints must track a Jiti fallback candidate");
+  }
+  for (const entrypoint of report.entrypoints) {
+    if (entrypoint.loaderPrimary === "tsx" && (!entrypoint.captureUsesTsx || !entrypoint.syntheticUsesTsx)) {
+      errors.push(`${entrypoint.id}: tsx loader strategy is not reflected in capture and synthetic commands`);
+    }
+  }
+  return errors;
+}
+
+export async function writePlatformProbes(report, options = {}) {
+  return writeJsonMarkdownArtifacts({
+    jsonPath: options.jsonPath,
+    markdownPath: options.markdownPath,
+    json: report,
+    markdown: renderPlatformProbesMarkdown(report, options),
+    check: options.check,
+  });
+}
+
+export function renderPlatformProbesMarkdown(report, options = {}) {
+  return [
+    `# ${options.title ?? "Plugin Inspector Platform And Loader Probes"}`,
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Mode: ${report.mode}`,
+    `Targets: ${report.targets.join(", ")}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(Object.entries(report.summary).map(([key, value]) => [key, value]), ["Metric", "Value"]),
+    "",
+    "## Loader Probes",
+    "",
+    markdownTable(
+      report.entrypoints.map((entrypoint) => [
+        entrypoint.fixture,
+        entrypoint.status,
+        entrypoint.loaderPrimary,
+        entrypoint.loaderAlternatives.join(", ") || "-",
+        entrypoint.captureUsesTsx ? "yes" : "no",
+        entrypoint.syntheticUsesTsx ? "yes" : "no",
+        entrypoint.entrypoint,
+      ]),
+      ["Fixture", "Status", "Primary", "Alternatives", "Capture TSX", "Synthetic TSX", "Entrypoint"],
+    ),
+    "",
+    "## Portability Findings",
+    "",
+    markdownTable(
+      report.portabilityFindings.map((finding) => [
+        finding.fixture,
+        finding.kind,
+        finding.platforms.join(", ") || "-",
+        finding.riskCodes.join(", "),
+        finding.mitigation,
+      ]),
+      ["Fixture", "Step", "Platforms", "Risks", "Mitigation"],
+    ),
+    "",
+    "## Recommendations",
+    "",
+    markdownTable(
+      report.recommendations.map((recommendation) => [recommendation.area, recommendation.action]),
+      ["Area", "Action"],
+    ),
+  ].join("\n");
+}
+
+function summarizeEntrypoint(fixtureId, entrypoint) {
+  const captureStep = entrypoint.steps.find((step) => step.kind === "capture");
+  const syntheticStep = entrypoint.steps.find((step) => step.kind === "synthetic-probe");
+  return {
+    fixture: fixtureId,
+    id: entrypoint.id,
+    status: entrypoint.status,
+    entrypoint: entrypoint.entrypoint,
+    packageManager: entrypoint.packageManager,
+    loaderSource: entrypoint.loaderStrategy.source,
+    loaderPrimary: entrypoint.loaderStrategy.primary,
+    loaderAlternatives: entrypoint.loaderStrategy.alternatives,
+    capturePlanned: Boolean(captureStep),
+    syntheticProbePlanned: Boolean(syntheticStep),
+    captureUsesTsx: Boolean(captureStep?.command.includes("--import tsx")),
+    syntheticUsesTsx: Boolean(syntheticStep?.command.includes("--import tsx")),
+  };
+}
+
+function summarizeStep(fixtureId, entrypoint, step) {
+  const riskCodes = stepRiskCodes(step);
+  return {
+    fixture: fixtureId,
+    entrypoint: entrypoint.id,
+    kind: step.kind,
+    platforms: platformsForRiskCodes(riskCodes),
+    riskCodes,
+    command: step.command,
+    mitigation: mitigationForRiskCodes(riskCodes),
+  };
+}
+
+function stepRiskCodes(step) {
+  const risks = new Set();
+  if (/\bmkdir -p\b/.test(step.command)) {
+    risks.add("posix-mkdir");
+  }
+  if (/\brsync\b/.test(step.command)) {
+    risks.add("rsync-required");
+  }
+  if (/^[A-Z0-9_]+=/.test(step.command)) {
+    risks.add("posix-env-prefix");
+  }
+  if (/\|\|\s*true/.test(step.command)) {
+    risks.add("posix-null-failure");
+  }
+  if (/\s>\s/.test(step.command)) {
+    risks.add("shell-redirection");
+  }
+  if (step.command.includes("--import tsx")) {
+    risks.add("tsx-loader-runtime");
+  }
+  if (/^(pnpm|yarn|bun)\b/.test(step.command)) {
+    risks.add("package-manager-availability");
+  }
+  return [...risks].sort();
+}
+
+function platformsForRiskCodes(riskCodes) {
+  const platforms = new Set();
+  for (const code of riskCodes) {
+    if (["posix-mkdir", "rsync-required", "posix-env-prefix", "posix-null-failure"].includes(code)) {
+      platforms.add("windows");
+    }
+    if (["rsync-required", "package-manager-availability"].includes(code)) {
+      platforms.add("container");
+    }
+    if (code === "package-manager-availability") {
+      platforms.add("linux");
+      platforms.add("macos");
+      platforms.add("windows");
+    }
+  }
+  return [...platforms].sort();
+}
+
+function mitigationForRiskCodes(riskCodes) {
+  const mitigations = {
+    "package-manager-availability": "install the declared package manager before isolated execution",
+    "posix-env-prefix": "run isolated commands through a Node wrapper or set env via the runner API",
+    "posix-mkdir": "replace shell mkdir with fs.mkdir({ recursive: true }) in the executor",
+    "posix-null-failure": "capture audit failures in the executor instead of relying on shell fallthrough",
+    "rsync-required": "copy workspaces with a Node fs.cp fallback before Windows/container lanes",
+    "shell-redirection": "write audit JSON from the executor instead of shell redirection",
+    "tsx-loader-runtime": "verify TS source entrypoints with tsx and Jiti loader lanes",
+  };
+  return riskCodes.map((code) => mitigations[code]).filter(Boolean).join("; ");
+}
+
+function buildRecommendations(portabilityFindings, entrypoints) {
+  const recommendations = [];
+  if (entrypoints.some((entrypoint) => entrypoint.loaderPrimary === "tsx")) {
+    recommendations.push({
+      area: "loader",
+      action: "keep tsx as the source-entrypoint smoke path, add a Jiti execution lane before treating TS plugin source compatibility as covered",
+    });
+  }
+  if (portabilityFindings.some((finding) => finding.riskCodes.includes("rsync-required"))) {
+    recommendations.push({
+      area: "workspace-copy",
+      action: "move isolated workspace copy into Node fs.cp so Windows and slim containers do not depend on rsync",
+    });
+  }
+  if (portabilityFindings.some((finding) => finding.riskCodes.includes("posix-env-prefix"))) {
+    recommendations.push({
+      area: "executor",
+      action: "replace shell env-prefix commands with structured spawn env for Windows parity",
+    });
+  }
+  return recommendations;
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}

package/src/process-profile.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+
+export async function runProfiledProcess(options) {
+  const start = performance.now();
+  const heapStartMb = heapUsedMb();
+  let firstRssKb = 0;
+  let peakRssKb = 0;
+  let peakCpuPercent = 0;
+  const cpuSamples = [];
+  let pollInFlight = false;
+
+  const child = spawn(options.command, options.args ?? [], {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
+  });
+  const stdout = [];
+  const stderr = [];
+  child.stdout?.on("data", (chunk) => stdout.push(chunk));
+  child.stderr?.on("data", (chunk) => stderr.push(chunk));
+
+  const recordStats = (stats) => {
+    if (stats.rssKb > 0 && firstRssKb === 0) {
+      firstRssKb = stats.rssKb;
+    }
+    peakRssKb = Math.max(peakRssKb, stats.rssKb);
+    peakCpuPercent = Math.max(peakCpuPercent, stats.cpuPercent);
+    if (stats.cpuPercent > 0) {
+      cpuSamples.push(stats.cpuPercent);
+    }
+  };
+
+  const poll = setInterval(() => {
+    if (pollInFlight) {
+      return;
+    }
+    pollInFlight = true;
+    readProcessStats(child.pid)
+      .then(recordStats)
+      .finally(() => {
+        pollInFlight = false;
+      });
+  }, options.pollMs ?? 100);
+
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on("error", (error) => {
+      clearInterval(poll);
+      reject(error);
+    });
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+  clearInterval(poll);
+
+  const finalStats = await readProcessStats(child.pid);
+  if (finalStats.rssKb > 0 && firstRssKb === 0) {
+    firstRssKb = finalStats.rssKb;
+  }
+  peakRssKb = Math.max(peakRssKb, finalStats.rssKb);
+  peakCpuPercent = Math.max(peakCpuPercent, finalStats.cpuPercent);
+  if (finalStats.cpuPercent > 0) {
+    cpuSamples.push(finalStats.cpuPercent);
+  }
+
+  const wallMs = Math.round(performance.now() - start);
+  const averageCpuPercent =
+    cpuSamples.length > 0
+      ? cpuSamples.reduce((sum, value) => sum + value, 0) / cpuSamples.length
+      : 0;
+  const cpuPercentForEstimate =
+    options.roundAverageCpuPercent === true
+      ? Math.round(averageCpuPercent * 10) / 10
+      : averageCpuPercent;
+
+  return {
+    wallMs,
+    peakRssMb: Math.round((peakRssKb / 1024) * 10) / 10,
+    rssDeltaMb: Math.round(((peakRssKb - firstRssKb) / 1024) * 10) / 10,
+    peakCpuPercent: Math.round(peakCpuPercent * 10) / 10,
+    cpuMsEstimate: Math.round((wallMs * cpuPercentForEstimate) / 100),
+    harnessHeapDeltaMb: Math.round((heapUsedMb() - heapStartMb) * 10) / 10,
+    exitCode,
+    stdoutPreview: previewLines(stdout),
+    stderrPreview: previewLines(stderr),
+  };
+}
+
+async function readProcessStats(pid) {
+  if (!pid || process.platform === "win32") {
+    return { rssKb: 0, cpuPercent: 0 };
+  }
+  return new Promise((resolve) => {
+    const ps = spawn("ps", ["-o", "rss=", "-o", "%cpu=", "-p", String(pid)], {
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const chunks = [];
+    ps.stdout.on("data", (chunk) => chunks.push(chunk));
+    ps.on("error", () => resolve({ rssKb: 0, cpuPercent: 0 }));
+    ps.on("exit", () => {
+      const [rssRaw, cpuRaw] = Buffer.concat(chunks).toString("utf8").trim().split(/\s+/);
+      const rssKb = Number.parseInt(rssRaw, 10);
+      const cpuPercent = Number.parseFloat(cpuRaw);
+      resolve({
+        rssKb: Number.isFinite(rssKb) ? rssKb : 0,
+        cpuPercent: Number.isFinite(cpuPercent) ? cpuPercent : 0,
+      });
+    });
+  });
+}
+
+function heapUsedMb() {
+  return Math.round((process.memoryUsage().heapUsed / 1024 / 1024) * 10) / 10;
+}
+
+function previewLines(chunks) {
+  return Buffer.concat(chunks).toString("utf8").trim().split("\n").slice(-2).join("\n");
+}

package/src/profile-diff.js

@@ -0,0 +1,222 @@
+import path from "node:path";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { readJsonFile, readOptionalJsonFile } from "./json-file.js";
+import { resolveRequiredFromRoot } from "./path-utils.js";
+
+export const defaultProfileDiffOptions = {
+  baselinePath: "baselines/runtime/main.json",
+  generatedAt: "deterministic",
+  jsonPath: "reports/plugin-runtime-profile-diff.json",
+  markdownPath: "reports/plugin-runtime-profile-diff.md",
+  policyPath: "plugin-inspector.policy.json",
+  reportTitle: "Plugin Runtime Profile Diff",
+};
+
+export async function buildProfileDiff(options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const policy =
+    options.policy ?? (await readJsonFile(profileDiffPath(rootDir, options.policyPath ?? defaultProfileDiffOptions.policyPath)));
+  const current = options.current ?? (await readJsonFile(profileDiffPath(rootDir, options.currentPath)));
+  const baseline =
+    options.baseline ??
+    (await readOptionalJsonFile(profileDiffPath(rootDir, options.baselinePath ?? defaultProfileDiffOptions.baselinePath)));
+  const checks = baseline ? compareProfiles({ baseline, current, policy, strict: options.strict }) : [];
+
+  if (!baseline) {
+    checks.push({
+      id: "profile.baseline.missing",
+      action: "warn",
+      metric: "baseline",
+      message: "runtime profile baseline is missing",
+      baseline: null,
+      current: null,
+      delta: null,
+    });
+  }
+
+  return {
+    generatedAt: options.generatedAt ?? defaultProfileDiffOptions.generatedAt,
+    status: checks.some((check) => check.action === "fail") ? "fail" : "pass",
+    strict: Boolean(options.strict),
+    baseline: baseline ? profileSummary(baseline) : null,
+    current: profileSummary(current),
+    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 validateProfileDiff(diff) {
+  return diff.checks
+    .filter((check) => check.action === "fail")
+    .map((check) => `${check.id}: ${check.message}: baseline=${check.baseline}, current=${check.current}`);
+}
+
+export async function writeProfileDiff(diff, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const jsonPath = profileDiffPath(rootDir, options.jsonPath ?? defaultProfileDiffOptions.jsonPath);
+  const markdownPath = profileDiffPath(rootDir, options.markdownPath ?? defaultProfileDiffOptions.markdownPath);
+  return writeJsonMarkdownArtifacts({
+    jsonPath,
+    markdownPath,
+    json: diff,
+    markdown: renderProfileDiffMarkdown(diff, options),
+    check: options.check,
+  });
+}
+
+export function renderProfileDiffMarkdown(diff, options = {}) {
+  const title = options.title ?? options.reportTitle ?? defaultProfileDiffOptions.reportTitle;
+  return [
+    `# ${title}`,
+    "",
+    `Generated: ${diff.generatedAt}`,
+    `Status: ${diff.status.toUpperCase()}`,
+    `Strict: ${diff.strict}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(
+      [
+        ["Checks", diff.summary.checkCount],
+        ["Fail", diff.summary.failCount],
+        ["Warn", diff.summary.warnCount],
+        ["Pass", diff.summary.passCount],
+        ["Current runs", diff.current.runs],
+        ["Baseline runs", diff.baseline?.runs ?? "-"],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Checks",
+    "",
+    markdownTable(
+      diff.checks.map((check) => [
+        check.action,
+        check.id,
+        check.metric,
+        check.baseline ?? "-",
+        check.current ?? "-",
+        check.delta ?? "-",
+        check.percent === undefined ? "-" : `${check.percent}%`,
+        check.message,
+      ]),
+      ["Action", "ID", "Metric", "Baseline", "Current", "Delta", "Percent", "Message"],
+    ),
+  ].join("\n");
+}
+
+function compareProfiles({ baseline, current, policy, strict }) {
+  const thresholds = policy.thresholds;
+  const strictEligible = current.runs >= thresholds.strictMinimumSamples;
+  return [
+    percentCheck({
+      id: "profile.wall-p95",
+      metric: "p95WallMs",
+      baseline: baseline.summary.p95WallMs,
+      current: current.summary.p95WallMs,
+      threshold: thresholds.wallP95RegressionPercent,
+      strict,
+      strictEligible,
+    }),
+    absoluteCheck({
+      id: "profile.peak-rss",
+      metric: "maxPeakRssMb",
+      baseline: baseline.summary.maxPeakRssMb,
+      current: current.summary.maxPeakRssMb,
+      threshold: thresholds.peakRssRegressionMb,
+      strict,
+      strictEligible,
+    }),
+    absoluteCheck({
+      id: "profile.node-boot",
+      metric: "nodeBootWallMs",
+      baseline: commandWall(baseline, "node-boot"),
+      current: commandWall(current, "node-boot"),
+      threshold: thresholds.bootRegressionMs,
+      strict,
+      strictEligible,
+    }),
+    ...registrySurfaceChecks(baseline, current),
+  ];
+}
+
+function percentCheck({ id, metric, baseline, current, threshold, strict, strictEligible }) {
+  const delta = current - baseline;
+  const percent = baseline > 0 ? Math.round((delta / baseline) * 1000) / 10 : 0;
+  const exceeded = delta > 0 && percent > threshold;
+  return {
+    id,
+    action: exceeded ? (strict && strictEligible ? "fail" : "warn") : "pass",
+    metric,
+    message: exceeded
+      ? `${metric} regressed ${percent}% over baseline`
+      : `${metric} stayed within ${threshold}% regression threshold`,
+    baseline,
+    current,
+    delta,
+    percent,
+  };
+}
+
+function absoluteCheck({ id, metric, baseline, current, threshold, strict, strictEligible }) {
+  const delta = current - baseline;
+  const exceeded = delta > threshold;
+  return {
+    id,
+    action: exceeded ? (strict && strictEligible ? "fail" : "warn") : "pass",
+    metric,
+    message: exceeded
+      ? `${metric} regressed ${delta} over baseline`
+      : `${metric} stayed within ${threshold} absolute regression threshold`,
+    baseline,
+    current,
+    delta,
+  };
+}
+
+function registrySurfaceChecks(baseline, current) {
+  return [
+    "compatRecords",
+    "hookNames",
+    "apiRegistrars",
+    "capturedRegistrars",
+    "sdkExports",
+    "manifestFields",
+    "manifestContractFields",
+  ].map((metric) => ({
+    id: `registry.${metric}`,
+    action: "pass",
+    metric,
+    message: "registry surface delta is tracked as context",
+    baseline: baseline.targetOpenClaw[metric],
+    current: current.targetOpenClaw[metric],
+    delta: current.targetOpenClaw[metric] - baseline.targetOpenClaw[metric],
+  }));
+}
+
+function commandWall(profile, commandId) {
+  return profile.commands.find((command) => command.id === commandId)?.wallMs?.median ?? 0;
+}
+
+function profileSummary(profile) {
+  return {
+    runs: profile.runs,
+    summary: profile.summary,
+    targetOpenClaw: profile.targetOpenClaw,
+    fixtureInventory: profile.fixtureInventory,
+  };
+}
+
+function profileDiffPath(rootDir, candidatePath) {
+  return resolveRequiredFromRoot(rootDir, candidatePath, "profile diff");
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}