@openclaw/plugin-inspector 0.0.0 → 0.1.1

package/src/issues.js

@@ -0,0 +1,366 @@
+import { createHash } from "node:crypto";
+
+export const deprecatedCompatRecords = new Set([
+  "channel-env-vars",
+  "legacy-before-agent-start",
+  "legacy-root-sdk-import",
+  "provider-auth-env-vars",
+]);
+
+export const knownIssueCodes = new Set([
+  "before-tool-call-probe",
+  "channel-contract-probe",
+  "channel-env-vars",
+  "conversation-access-hook",
+  "legacy-before-agent-start",
+  "legacy-root-sdk-import",
+  "manifest-unknown-contracts",
+  "manifest-unknown-fields",
+  "missing-expected-seam",
+  "missing-compat-record",
+  "unknown-hook-name",
+  "unknown-registration-name",
+  "package-build-artifact-entrypoint",
+  "package-dependency-install-required",
+  "package-entrypoint-missing",
+  "package-json-missing",
+  "package-manifest-version-drift",
+  "package-openclaw-entry-missing",
+  "package-openclaw-metadata-missing",
+  "package-plugin-api-compat-missing",
+  "package-typescript-source-entrypoint",
+  "provider-auth-env-vars",
+  "registration-capture-gap",
+  "runtime-tool-capture",
+  "sdk-export-missing",
+]);
+
+export const issueMetadataByCode = {
+  "before-tool-call-probe": {
+    severity: "P1",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "before_tool_call needs terminal/block/approval probes",
+  },
+  "channel-contract-probe": {
+    severity: "P2",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "channel runtime needs envelope/config probes",
+  },
+  "channel-env-vars": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "channelEnvVars legacy manifest metadata must stay covered",
+  },
+  "conversation-access-hook": {
+    severity: "P1",
+    owner: "core",
+    decision: "inspector-follow-up",
+    title: "conversation-access hooks need privacy-boundary probes",
+  },
+  "legacy-before-agent-start": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "legacy before_agent_start hook compatibility is still used",
+  },
+  "legacy-root-sdk-import": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "root plugin SDK barrel is still used by fixtures",
+  },
+  "sdk-export-missing": {
+    severity: "P1",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "plugin SDK import aliases are missing from target package exports",
+  },
+  "missing-compat-record": {
+    severity: "P1",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "compat-dependent behavior lacks registry coverage",
+  },
+  "missing-expected-seam": {
+    severity: "P0",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "fixture no longer exposes an expected seam",
+  },
+  "manifest-unknown-contracts": {
+    severity: "P1",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "manifest declares unsupported contract keys",
+  },
+  "manifest-unknown-fields": {
+    severity: "P2",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "manifest uses unsupported top-level fields",
+  },
+  "package-build-artifact-entrypoint": {
+    severity: "P2",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "cold import requires package build output",
+  },
+  "package-dependency-install-required": {
+    severity: "P2",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "cold import requires isolated dependency installation",
+  },
+  "package-entrypoint-missing": {
+    severity: "P1",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "OpenClaw package entrypoint is missing",
+  },
+  "package-json-missing": {
+    severity: "P2",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "package metadata is missing",
+  },
+  "package-manifest-version-drift": {
+    severity: "P2",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "package and manifest versions drift",
+  },
+  "package-openclaw-entry-missing": {
+    severity: "P2",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "OpenClaw package entrypoint metadata is missing",
+  },
+  "package-openclaw-metadata-missing": {
+    severity: "P2",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "OpenClaw package metadata is missing",
+  },
+  "package-plugin-api-compat-missing": {
+    severity: "P2",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "plugin API compatibility range is missing",
+  },
+  "package-typescript-source-entrypoint": {
+    severity: "P2",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "cold import needs TypeScript source entrypoint support",
+  },
+  "provider-auth-env-vars": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "providerAuthEnvVars legacy manifest metadata must stay covered",
+  },
+  "registration-capture-gap": {
+    severity: "P1",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "runtime registrations need capture before contract judgment",
+  },
+  "runtime-tool-capture": {
+    severity: "P2",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: "runtime tool schema needs registration capture",
+  },
+  "unknown-hook-name": {
+    severity: "P0",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "fixture uses a hook missing from target OpenClaw",
+  },
+  "unknown-registration-name": {
+    severity: "P0",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "fixture calls a registrar missing from target OpenClaw",
+  },
+};
+
+export function buildIssues({ breakages = [], warnings = [], suggestions = [], targetOpenClaw, idPrefix = "CRABPOT" }) {
+  const findings = [
+    ...breakages.map((finding) => issueMetadata({ ...finding, severity: "P0" }, targetOpenClaw)),
+    ...warnings.map((finding) => issueMetadata(finding, targetOpenClaw)),
+    ...suggestions.map((finding) => issueMetadata(finding, targetOpenClaw)),
+  ];
+
+  return findings
+    .filter((finding) => finding.severity)
+    .sort(issueSort)
+    .map((finding) => ({
+      id: issueId(finding, { prefix: idPrefix }),
+      fixture: finding.fixture,
+      severity: finding.severity,
+      owner: finding.owner,
+      code: finding.code,
+      decision: finding.decision,
+      status: finding.severity === "P0" || finding.level === "breakage" ? "blocking" : "open",
+      issueClass: finding.issueClass,
+      live: finding.live,
+      deprecated: finding.deprecated,
+      compatStatus: finding.compatStatus,
+      title: issueTitle(finding),
+      evidence: finding.evidence ?? [],
+      compatRecord: finding.compatRecord ?? null,
+    }));
+}
+
+export function issueId(finding, options = {}) {
+  const stableKey = [
+    finding.fixture,
+    finding.code,
+    finding.severity,
+    finding.compatRecord ?? "",
+    ...(finding.evidence ?? []),
+  ].join("\n");
+  return `${options.prefix ?? "CRABPOT"}-${createHash("sha256").update(stableKey).digest("hex").slice(0, 8).toUpperCase()}`;
+}
+
+export function issueMetadata(finding, targetOpenClaw) {
+  const metadata = issueMetadataByCode[finding.code] ?? {
+    severity: "P3",
+    owner: "inspector",
+    decision: "inspector-follow-up",
+    title: finding.message,
+  };
+  return {
+    ...finding,
+    ...metadata,
+    ...classifyIssueFinding(finding, targetOpenClaw, metadata),
+  };
+}
+
+export function classifyIssueFinding(finding, targetOpenClaw, metadata = {}) {
+  const compatStatus = compatStatusFor(finding, targetOpenClaw);
+  const deprecated = compatStatus === "deprecated";
+  const code = finding.code;
+  const issueClass = issueClassFor(code, { deprecated, compatRecord: finding.compatRecord });
+  const live = issueClass === "live-issue" || finding.level === "breakage";
+  const severity = severityForClass(code, metadata?.severity, {
+    issueClass,
+    compatRecord: finding.compatRecord,
+    compatStatus,
+  });
+
+  return {
+    compatStatus,
+    deprecated,
+    issueClass,
+    live,
+    severity,
+  };
+}
+
+export function summarizeIssueClasses(issues) {
+  const summary = {
+    "compat-gap": 0,
+    "deprecation-warning": 0,
+    "fixture-regression": 0,
+    "inspector-gap": 0,
+    "live-issue": 0,
+    "upstream-metadata": 0,
+  };
+  for (const issue of issues) {
+    summary[issue.issueClass] = (summary[issue.issueClass] ?? 0) + 1;
+  }
+  return summary;
+}
+
+function issueClassFor(code, options) {
+  if (["unknown-hook-name", "unknown-registration-name", "package-entrypoint-missing", "sdk-export-missing"].includes(code)) {
+    return "live-issue";
+  }
+  if (code === "missing-compat-record") {
+    return "compat-gap";
+  }
+  if (options.deprecated || ["channel-env-vars", "legacy-before-agent-start", "legacy-root-sdk-import", "provider-auth-env-vars"].includes(code)) {
+    return "deprecation-warning";
+  }
+  if (
+    [
+      "before-tool-call-probe",
+      "channel-contract-probe",
+      "conversation-access-hook",
+      "package-build-artifact-entrypoint",
+      "package-dependency-install-required",
+      "package-typescript-source-entrypoint",
+      "registration-capture-gap",
+      "runtime-tool-capture",
+    ].includes(code)
+  ) {
+    return "inspector-gap";
+  }
+  if (
+    [
+      "manifest-unknown-contracts",
+      "manifest-unknown-fields",
+      "package-json-missing",
+      "package-manifest-version-drift",
+      "package-openclaw-entry-missing",
+      "package-openclaw-metadata-missing",
+      "package-plugin-api-compat-missing",
+    ].includes(code)
+  ) {
+    return "upstream-metadata";
+  }
+  if (code === "missing-expected-seam") {
+    return "fixture-regression";
+  }
+  return options.compatRecord ? "compat-gap" : "inspector-gap";
+}
+
+function severityForClass(code, defaultSeverity, options) {
+  if (
+    options.issueClass === "live-issue" &&
+    ["none", "untracked"].includes(options.compatStatus) &&
+    ["unknown-hook-name", "unknown-registration-name", "package-entrypoint-missing", "sdk-export-missing"].includes(code)
+  ) {
+    return "P0";
+  }
+  return defaultSeverity ?? "P3";
+}
+
+function compatStatusFor(finding, targetOpenClaw) {
+  if (finding.code === "missing-compat-record") {
+    return "missing";
+  }
+  if (!finding.compatRecord) {
+    return "none";
+  }
+  const targetStatus = targetOpenClaw?.compatRecordStatuses?.[finding.compatRecord];
+  if (targetStatus) {
+    return targetStatus;
+  }
+  if (deprecatedCompatRecords.has(finding.compatRecord)) {
+    return "deprecated";
+  }
+  return "untracked";
+}
+
+function issueSort(left, right) {
+  return (
+    priorityRank(left.severity) - priorityRank(right.severity) ||
+    left.fixture.localeCompare(right.fixture) ||
+    left.code.localeCompare(right.code) ||
+    (left.evidence ?? []).join(",").localeCompare((right.evidence ?? []).join(","))
+  );
+}
+
+function issueTitle(finding) {
+  return `${finding.fixture}: ${finding.title ?? finding.message}`;
+}
+
+function priorityRank(priority) {
+  return { P0: 0, P1: 1, P2: 2, P3: 3 }[priority] ?? 4;
+}

package/src/json-file.js

@@ -0,0 +1,10 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+export async function readJsonFile(jsonPath) {
+  return JSON.parse(await readFile(jsonPath, "utf8"));
+}
+
+export async function readOptionalJsonFile(jsonPath) {
+  return existsSync(jsonPath) ? readJsonFile(jsonPath) : null;
+}

package/src/mock-sdk-capture-runner.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { mkdtemp, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createCaptureApi } from "./capture-api.js";
+import { createMockSdkPackage } from "./sdk-mock.js";
+
+const options = JSON.parse(process.argv[2] ?? "{}");
+
+try {
+  const result = await run(options);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`${error.stack ?? error.message}\n`);
+  process.exitCode = 1;
+}
+
+async function run(options) {
+  const entrypoint = path.resolve(options.cwd ?? process.cwd(), options.entrypoint);
+  const pluginRoot = path.resolve(options.cwd ?? process.cwd(), options.pluginRoot ?? path.dirname(entrypoint));
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-mock-sdk-"));
+
+  try {
+    await createMockSdkPackage(workspace);
+    const linkedPluginRoot = path.join(workspace, "plugin");
+    await symlink(pluginRoot, linkedPluginRoot, "junction");
+    const linkedEntrypoint = path.join(linkedPluginRoot, path.relative(pluginRoot, entrypoint));
+    return await captureLinkedEntrypoint(linkedEntrypoint, options);
+  } finally {
+    await rm(workspace, { force: true, recursive: true });
+  }
+}
+
+async function captureLinkedEntrypoint(entrypoint, options) {
+  const module = await import(pathToFileURL(entrypoint).href);
+  const register = findRegisterExport(module);
+
+  if (!register) {
+    return {
+      status: "no-register-export",
+      entrypoint: options.entrypoint,
+      mockSdk: true,
+      captured: [],
+    };
+  }
+
+  const api = createCaptureApi(options.apiOptions);
+  await register(api);
+  return {
+    status: "captured",
+    entrypoint: options.entrypoint,
+    mockSdk: true,
+    captured: api.getCapturedContracts(),
+  };
+}
+
+function findRegisterExport(module) {
+  if (typeof module.register === "function") {
+    return module.register;
+  }
+  if (typeof module.default === "function") {
+    return module.default;
+  }
+  if (typeof module.default?.register === "function") {
+    return module.default.register;
+  }
+  return null;
+}

package/src/openclaw-target.js

@@ -0,0 +1,179 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const defaultOpenClawCheckoutPaths = ["./openclaw", "../openclaw"];
+
+export async function readOpenClawTargetSurface(options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const configuredPath = options.configuredPath;
+
+  if (configuredPath === false) {
+    return emptyTargetSurface({ configuredPath: null, status: "disabled" });
+  }
+
+  const requestedPaths = openClawTargetPathCandidates(options.manifest, configuredPath);
+  if (requestedPaths.length === 0) {
+    return emptyTargetSurface({ configuredPath: null, status: "not-configured" });
+  }
+
+  const match = findTargetCheckout(rootDir, requestedPaths);
+  if (!match) {
+    return emptyTargetSurface({
+      configuredPath: requestedPaths[0],
+      searchedPaths: requestedPaths,
+      status: "missing",
+    });
+  }
+
+  const { requestedPath, resolvedPath, registryPath } = match;
+  const hookTypesPath = path.join(resolvedPath, "src/plugins/hook-types.ts");
+  const apiBuilderPath = path.join(resolvedPath, "src/plugins/api-builder.ts");
+  const capturedRegistrationPath = path.join(resolvedPath, "src/plugins/captured-registration.ts");
+  const manifestTypesPath = path.join(resolvedPath, "src/plugins/manifest.ts");
+  const packagePath = path.join(resolvedPath, "package.json");
+
+  const registrySource = await readFile(registryPath, "utf8");
+  const compatRecordEntries = parseCompatRecordEntries(registrySource);
+  const hookTypesSource = existsSync(hookTypesPath) ? await readFile(hookTypesPath, "utf8") : "";
+  const hookNames = hookTypesSource ? parseExportedStringArray(hookTypesSource, "PLUGIN_HOOK_NAMES") : [];
+  const apiBuilderSource = existsSync(apiBuilderPath) ? await readFile(apiBuilderPath, "utf8") : "";
+  const apiRegistrars = apiBuilderSource ? parseApiRegistrars(apiBuilderSource) : [];
+  const manifestTypesSource = existsSync(manifestTypesPath) ? await readFile(manifestTypesPath, "utf8") : "";
+  const manifestFields = manifestTypesSource ? parseTypeFields(manifestTypesSource, "PluginManifest") : [];
+  const manifestContractFields = manifestTypesSource ? parseTypeFields(manifestTypesSource, "PluginManifestContracts") : [];
+  const capturedRegistrars = existsSync(capturedRegistrationPath)
+    ? parseCapturedRegistrars(await readFile(capturedRegistrationPath, "utf8"))
+    : [];
+  const sdkExports = existsSync(packagePath)
+    ? parsePluginSdkExports(JSON.parse(await readFile(packagePath, "utf8")))
+    : [];
+
+  return {
+    configuredPath: requestedPath,
+    searchedPaths: requestedPaths,
+    status: "ok",
+    compatRegistryPath: relativePath(rootDir, registryPath),
+    compatRecordCount: compatRecordEntries.length,
+    compatRecords: compatRecordEntries.map((record) => record.code).sort(),
+    compatRecordStatuses: Object.fromEntries(compatRecordEntries.map((record) => [record.code, record.status])),
+    hookTypesPath: existsSync(hookTypesPath) ? relativePath(rootDir, hookTypesPath) : null,
+    hookNameCount: hookNames.length,
+    hookNames,
+    apiBuilderPath: existsSync(apiBuilderPath) ? relativePath(rootDir, apiBuilderPath) : null,
+    apiRegistrarCount: apiRegistrars.length,
+    apiRegistrars,
+    capturedRegistrationPath: existsSync(capturedRegistrationPath) ? relativePath(rootDir, capturedRegistrationPath) : null,
+    capturedRegistrarCount: capturedRegistrars.length,
+    capturedRegistrars,
+    packagePath: existsSync(packagePath) ? relativePath(rootDir, packagePath) : null,
+    sdkExportCount: sdkExports.length,
+    sdkExports,
+    manifestTypesPath: existsSync(manifestTypesPath) ? relativePath(rootDir, manifestTypesPath) : null,
+    manifestFieldCount: manifestFields.length,
+    manifestFields,
+    manifestContractFieldCount: manifestContractFields.length,
+    manifestContractFields,
+  };
+}
+
+export function openClawTargetPathCandidates(manifest, configuredPath) {
+  if (typeof configuredPath === "string") {
+    return [configuredPath];
+  }
+  return unique([manifest?.openclaw?.defaultCheckoutPath, ...defaultOpenClawCheckoutPaths].filter(Boolean));
+}
+
+export function parseCompatRecordEntries(source) {
+  const entries = [];
+  for (const match of source.matchAll(/\{[\s\S]*?\bcode:\s*["'`]([^"'`]+)["'`][\s\S]*?\bstatus:\s*["'`]([^"'`]+)["'`][\s\S]*?\}/g)) {
+    entries.push({ code: match[1], status: match[2] });
+  }
+  return dedupeBy(entries, (entry) => entry.code).sort((left, right) => left.code.localeCompare(right.code));
+}
+
+export function parsePluginSdkExports(packageJson) {
+  return Object.keys(packageJson.exports ?? {})
+    .filter((specifier) => specifier === "./plugin-sdk" || specifier.startsWith("./plugin-sdk/"))
+    .map((specifier) => `openclaw/${specifier.slice(2)}`)
+    .sort();
+}
+
+export function parseExportedStringArray(source, exportName) {
+  const match = source.match(new RegExp(`export\\s+const\\s+${exportName}\\s*=\\s*\\[([\\s\\S]*?)\\]\\s+as\\s+const`));
+  if (!match) {
+    return [];
+  }
+
+  return unique([...match[1].matchAll(/["'`]([^"'`]+)["'`]/g)].map((item) => item[1])).sort();
+}
+
+export function parseTypeFields(source, typeName) {
+  const marker = `export type ${typeName} = {`;
+  const start = source.indexOf(marker);
+  if (start === -1) {
+    return [];
+  }
+  const bodyStart = start + marker.length;
+  const end = source.indexOf("\n};", bodyStart);
+  if (end === -1) {
+    return [];
+  }
+  const body = source.slice(bodyStart, end);
+  return unique(
+    [...body.matchAll(/^\s*([A-Za-z][A-Za-z0-9]*)\??:/gm)]
+      .map((match) => match[1])
+      .filter((field) => !field.startsWith("PluginManifest")),
+  ).sort();
+}
+
+function findTargetCheckout(rootDir, requestedPaths) {
+  for (const requestedPath of requestedPaths) {
+    const resolvedPath = path.resolve(rootDir, requestedPath);
+    const registryPath = path.join(resolvedPath, "src/plugins/compat/registry.ts");
+    if (existsSync(registryPath)) {
+      return { requestedPath, resolvedPath, registryPath };
+    }
+  }
+  return null;
+}
+
+function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status }) {
+  return {
+    configuredPath,
+    searchedPaths,
+    status,
+    compatRecords: [],
+    compatRecordStatuses: {},
+    hookNames: [],
+    apiRegistrars: [],
+    capturedRegistrars: [],
+    sdkExports: [],
+    manifestFields: [],
+    manifestContractFields: [],
+  };
+}
+
+function parseCapturedRegistrars(source) {
+  return unique([...source.matchAll(/^\s*(register[A-Za-z0-9]+)\s*\(/gm)].map((match) => match[1])).sort();
+}
+
+function parseApiRegistrars(source) {
+  return unique([...source.matchAll(/\b(register[A-Za-z0-9]+)\b/g)].map((match) => match[1])).sort();
+}
+
+function relativePath(rootDir, filePath) {
+  return path.relative(rootDir, filePath).replaceAll("\\", "/");
+}
+
+function dedupeBy(values, keyForValue) {
+  const byKey = new Map();
+  for (const value of values) {
+    byKey.set(keyForValue(value), value);
+  }
+  return [...byKey.values()];
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}

package/src/path-utils.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+
+export function resolveFromRoot(rootDir, value) {
+  return path.isAbsolute(value) ? value : path.join(rootDir, value);
+}
+
+export function resolveRequiredFromRoot(rootDir, value, label) {
+  if (!value) {
+    throw new Error(`${label} path is required`);
+  }
+  return resolveFromRoot(rootDir, value);
+}
+
+export function toRepoPath(value) {
+  return normalizeRepoPath(value).replaceAll(path.sep, "/");
+}
+
+export function normalizeRepoPath(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+export function posixJoin(...parts) {
+  return parts.filter(Boolean).join("/").replace(/\/+/g, "/");
+}
+
+export function slugForArtifact(value) {
+  return String(value).replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "");
+}