@openclaw/plugin-inspector 0.1.1 → 0.1.2

package/src/config.js

@@ -52,6 +52,19 @@ export function validateInspectorConfig(config) {
     errors.push("config.fixtures must be a non-empty array");
   }
 
+  if (config.capture !== undefined) {
+    if (!config.capture || typeof config.capture !== "object" || Array.isArray(config.capture)) {
+      errors.push("config.capture must be an object when present");
+    } else {
+      if (config.capture.runtime !== undefined && typeof config.capture.runtime !== "boolean") {
+        errors.push("config.capture.runtime must be a boolean when present");
+      }
+      if (config.capture.mockSdk !== undefined && typeof config.capture.mockSdk !== "boolean") {
+        errors.push("config.capture.mockSdk must be a boolean when present");
+      }
+    }
+  }
+
   const ids = new Set();
   const paths = new Set();
   for (const fixture of config.fixtures ?? []) {
@@ -134,6 +147,7 @@ export async function normalizePluginRootConfig(config, options = {}) {
   return {
     version: 1,
     submoduleRoot: ".",
+    capture: config.capture,
     openclaw: config.openclaw,
     fixtures: [fixture],
   };
@@ -157,7 +171,7 @@ async function readJsonIfExists(filePath) {
   return JSON.parse(await readFile(filePath, "utf8"));
 }
 
-function packageId(packageName) {
+export function packageId(packageName) {
   if (!packageName) {
     return null;
   }
@@ -170,7 +184,7 @@ function packageId(packageName) {
     .toLowerCase();
 }
 
-function inferPluginSeams(pluginManifest, packageJson) {
+export function inferPluginSeams(pluginManifest, packageJson) {
   const contracts = Object.keys(pluginManifest?.contracts ?? {});
   if (contracts.includes("tools")) {
     return ["dynamic-tool"];

package/src/index.js

@@ -6,5 +6,6 @@ export {
   loadPluginConfig,
   renderTextSummary,
   runPluginCheck,
+  setupPluginInspector,
   writePluginReports,
 } from "./api.js";

package/src/init.js

@@ -0,0 +1,150 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { inferPluginSeams, packageId } from "./config.js";
+
+export const defaultInitConfigPath = "plugin-inspector.config.json";
+export const defaultInitWorkflowPath = ".github/workflows/plugin-inspector.yml";
+
+export async function writePluginInspectorInit(options = {}) {
+  const pluginRoot = path.resolve(options.pluginRoot ?? options.cwd ?? process.cwd());
+  const configPath = path.resolve(pluginRoot, options.configPath ?? defaultInitConfigPath);
+  const written = [];
+
+  if (existsSync(configPath) && options.force !== true) {
+    throw new Error(`${path.relative(pluginRoot, configPath)} already exists; pass --force to overwrite it`);
+  }
+
+  const config = await buildPluginInspectorConfig({ pluginRoot });
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  written.push(configPath);
+
+  if (options.ci === true) {
+    const workflowPath = path.resolve(pluginRoot, options.workflowPath ?? defaultInitWorkflowPath);
+    if (existsSync(workflowPath) && options.force !== true) {
+      throw new Error(`${path.relative(pluginRoot, workflowPath)} already exists; pass --force to overwrite it`);
+    }
+    await mkdir(path.dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, renderGithubActionsWorkflow({ packageManager: options.packageManager }), "utf8");
+    written.push(workflowPath);
+  }
+
+  return { pluginRoot, configPath, written };
+}
+
+export async function buildPluginInspectorConfig(options = {}) {
+  const pluginRoot = path.resolve(options.pluginRoot ?? options.cwd ?? process.cwd());
+  const packageJson = await readJsonIfExists(path.join(pluginRoot, "package.json"));
+  const pluginManifest = await readJsonIfExists(path.join(pluginRoot, "openclaw.plugin.json"));
+  const sourceRoot = inferSourceRoot(packageJson);
+
+  const plugin = {
+    id: pluginManifest?.id ?? packageId(packageJson?.name) ?? "plugin",
+    priority: "high",
+    seams: inferPluginSeams(pluginManifest, packageJson),
+  };
+
+  if (sourceRoot !== ".") {
+    plugin.sourceRoot = sourceRoot;
+  }
+
+  return {
+    version: 1,
+    plugin,
+    capture: {
+      mockSdk: true,
+    },
+  };
+}
+
+export function renderGithubActionsWorkflow(options = {}) {
+  const packageManager = normalizePackageManager(options.packageManager);
+  const setup = packageManagerSetup(packageManager);
+
+  return `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: ${setup.cache}
+${setup.corepack ? "      - run: corepack enable\n" : ""}      - run: ${setup.install}
+      - run: ${setup.exec} @openclaw/plugin-inspector check --no-openclaw
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 ${setup.exec} @openclaw/plugin-inspector check --no-openclaw --runtime --mock-sdk
+      - uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: plugin-inspector-reports
+          path: reports/plugin-inspector-*
+`;
+}
+
+function inferSourceRoot(packageJson) {
+  const entrypoints = [
+    packageJson?.openclaw?.entrypoint,
+    ...(packageJson?.openclaw?.extensions ?? []),
+    ...(packageJson?.openclaw?.runtimeExtensions ?? []),
+  ].filter((value) => typeof value === "string");
+  const entrypoint = entrypoints[0] ?? packageJson?.exports?.["."] ?? packageJson?.main ?? "src/index.js";
+  if (typeof entrypoint === "string" && entrypoint.startsWith("src/")) {
+    return "src";
+  }
+  return ".";
+}
+
+async function readJsonIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+function normalizePackageManager(packageManager = "npm") {
+  if (["npm", "pnpm", "yarn", "bun"].includes(packageManager)) {
+    return packageManager;
+  }
+  throw new Error("--package-manager must be npm, pnpm, yarn, or bun");
+}
+
+function packageManagerSetup(packageManager) {
+  if (packageManager === "pnpm") {
+    return {
+      cache: "pnpm",
+      corepack: true,
+      install: "pnpm install --frozen-lockfile",
+      exec: "pnpm dlx",
+    };
+  }
+  if (packageManager === "yarn") {
+    return {
+      cache: "yarn",
+      corepack: true,
+      install: "yarn install --immutable",
+      exec: "yarn dlx",
+    };
+  }
+  if (packageManager === "bun") {
+    return {
+      cache: "npm",
+      corepack: false,
+      install: "bun install --frozen-lockfile",
+      exec: "bunx",
+    };
+  }
+  return {
+    cache: "npm",
+    corepack: false,
+    install: "npm ci",
+    exec: "npx",
+  };
+}

package/src/inspector.js

@@ -156,7 +156,12 @@ export async function captureEntrypoint(entrypoint, options = {}) {
   }
 
   const resolvedEntrypoint = path.resolve(options.cwd ?? process.cwd(), entrypoint);
-  const module = await import(pathToFileURL(resolvedEntrypoint).href);
+  let module;
+  try {
+    module = await import(pathToFileURL(resolvedEntrypoint).href);
+  } catch (error) {
+    throw classifyCapturePhaseError(error, "entrypoint-import-error");
+  }
   const register = findRegisterExport(module);
 
   if (!register) {
@@ -168,7 +173,11 @@ export async function captureEntrypoint(entrypoint, options = {}) {
   }
 
   const api = createCaptureApi(options.apiOptions);
-  await register(api);
+  try {
+    await register(api);
+  } catch (error) {
+    throw classifyCapturePhaseError(error, "registration-execution-error");
+  }
   const result = {
     status: "captured",
     entrypoint: resolvedEntrypoint,
@@ -188,19 +197,85 @@ export async function captureEntrypointWithMockSdk(entrypoint, options = {}) {
     pluginRoot: options.pluginRoot,
     apiOptions: options.apiOptions,
   };
-  const { stdout } = await execFileAsync(
-    process.execPath,
-    ["--preserve-symlinks", runnerPath, JSON.stringify(payload)],
-    {
-      cwd: options.cwd ?? process.cwd(),
-      env: {
-        ...process.env,
-        ...(options.env ?? {}),
+  try {
+    const { stdout } = await execFileAsync(
+      process.execPath,
+      ["--no-warnings", "--preserve-symlinks", runnerPath, JSON.stringify(payload)],
+      {
+        cwd: options.cwd ?? process.cwd(),
+        env: {
+          ...process.env,
+          ...(options.env ?? {}),
+        },
+        maxBuffer: 1024 * 1024 * 10,
       },
-      maxBuffer: 1024 * 1024 * 10,
-    },
-  );
-  return JSON.parse(stdout);
+    );
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw classifyMockSdkCaptureError(error);
+  }
+}
+
+export function classifyMockSdkCaptureError(error) {
+  const rawMessage = [error?.stderr, error?.stdout, error?.message].filter(Boolean).join("\n");
+  const missingExport = rawMessage.match(/does not provide an export named ['"]([^'"]+)['"]/)?.[1];
+  if (missingExport) {
+    return enrichCaptureError(error, {
+      message: `Mock SDK import failed: openclaw/plugin-sdk is missing export ${missingExport}`,
+      failureClass: "missing-sdk-export",
+      missingExport,
+    });
+  }
+
+  const missingModule =
+    rawMessage.match(/Cannot find (?:package|module) ['"]([^'"]*openclaw\/plugin-sdk[^'"]*)['"]/)?.[1] ??
+    rawMessage.match(/Package subpath ['"](\.\/plugin-sdk\/[^'"]+)['"]/)?.[1];
+  if (missingModule || rawMessage.includes("openclaw/plugin-sdk")) {
+    return enrichCaptureError(error, {
+      message: `Mock SDK import failed: ${missingModule ?? "openclaw/plugin-sdk module could not be resolved"}`,
+      failureClass: "missing-sdk-module",
+      missingModule,
+    });
+  }
+
+  const failureClass = rawMessage.match(/\[plugin-inspector:([^\]]+)\]/)?.[1];
+  if (failureClass) {
+    return enrichCaptureError(error, {
+      message: firstMeaningfulErrorLine(rawMessage.replace(/\[plugin-inspector:[^\]]+\]/, "")) ?? "Mock SDK capture failed",
+      failureClass,
+    });
+  }
+
+  return enrichCaptureError(error, {
+    message: firstMeaningfulErrorLine(rawMessage) ?? "Mock SDK capture failed",
+    failureClass: "mock-sdk-capture-error",
+  });
+}
+
+export function classifyCapturePhaseError(error, failureClass) {
+  return enrichCaptureError(error, {
+    message: error instanceof Error ? error.message : String(error),
+    failureClass,
+  });
+}
+
+function enrichCaptureError(error, details) {
+  const wrapped = new Error(details.message, { cause: error });
+  wrapped.failureClass = details.failureClass;
+  if (details.missingExport) {
+    wrapped.missingExport = details.missingExport;
+  }
+  if (details.missingModule) {
+    wrapped.missingModule = details.missingModule;
+  }
+  return wrapped;
+}
+
+function firstMeaningfulErrorLine(message) {
+  return String(message)
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line && !line.startsWith("Command failed:"));
 }
 
 function findRegisterExport(module) {

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { mkdtemp, rm, symlink } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
+import { register } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -7,12 +8,16 @@ import { createCaptureApi } from "./capture-api.js";
 import { createMockSdkPackage } from "./sdk-mock.js";
 
 const options = JSON.parse(process.argv[2] ?? "{}");
+let activeOutputCapture = null;
 
 try {
   const result = await run(options);
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  writeRunnerStdout(`${JSON.stringify(result, null, 2)}\n`);
 } catch (error) {
-  process.stderr.write(`${error.stack ?? error.message}\n`);
+  if (error.failureClass) {
+    writeRunnerStderr(`[plugin-inspector:${error.failureClass}]\n`);
+  }
+  writeRunnerStderr(`${error.stack ?? error.message}\n`);
   process.exitCode = 1;
 }
 
@@ -22,37 +27,79 @@ async function run(options) {
   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);
+    const { loaderPath } = await createMockSdkPackage(workspace, { pluginRoot });
+    register(pathToFileURL(loaderPath));
+    return await captureLinkedEntrypoint(entrypoint, options);
   } finally {
     await rm(workspace, { force: true, recursive: true });
   }
 }
 
 async function captureLinkedEntrypoint(entrypoint, options) {
-  const module = await import(pathToFileURL(entrypoint).href);
+  const outputCapture = installProcessOutputCapture();
+  activeOutputCapture = outputCapture;
+
+  let module;
+  try {
+    module = await import(pathToFileURL(entrypoint).href);
+  } catch (error) {
+    await drainAsyncOutput();
+    throw capturePhaseError(error, "entrypoint-import-error");
+  }
   const register = findRegisterExport(module);
 
   if (!register) {
-    return {
-      status: "no-register-export",
-      entrypoint: options.entrypoint,
-      mockSdk: true,
-      captured: [],
-    };
+    await drainAsyncOutput();
+    return withProcessOutput(
+      {
+        status: "no-register-export",
+        entrypoint: options.entrypoint,
+        mockSdk: true,
+        captured: [],
+      },
+      outputCapture,
+    );
   }
 
   const api = createCaptureApi(options.apiOptions);
-  await register(api);
-  return {
+  try {
+    await register(api);
+  } catch (error) {
+    await drainAsyncOutput();
+    throw capturePhaseError(error, "registration-execution-error");
+  }
+  await drainAsyncOutput();
+
+  const result = {
     status: "captured",
     entrypoint: options.entrypoint,
     mockSdk: true,
     captured: api.getCapturedContracts(),
   };
+  if (options.apiOptions?.retainHandlers === true) {
+    result.retained = api.getRetainedContracts();
+  }
+  return withProcessOutput(result, outputCapture);
+}
+
+function withProcessOutput(result, outputCapture) {
+  const stdout = outputCapture.stdout();
+  const stderr = outputCapture.stderr();
+  if (stdout.length === 0 && stderr.length === 0) {
+    return result;
+  }
+  return {
+    ...result,
+    processOutput: {
+      stdout,
+      stderr,
+    },
+  };
+}
+
+function capturePhaseError(error, failureClass) {
+  error.failureClass = failureClass;
+  return error;
 }
 
 function findRegisterExport(module) {
@@ -67,3 +114,49 @@ function findRegisterExport(module) {
   }
   return null;
 }
+
+function installProcessOutputCapture() {
+  const stdoutChunks = [];
+  const stderrChunks = [];
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  process.stdout.write = (chunk, encoding, callback) => {
+    stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+    invokeWriteCallback(encoding, callback);
+    return true;
+  };
+  process.stderr.write = (chunk, encoding, callback) => {
+    stderrChunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+    invokeWriteCallback(encoding, callback);
+    return true;
+  };
+
+  return {
+    originalStdoutWrite,
+    originalStderrWrite,
+    stdout: () => stdoutChunks.join(""),
+    stderr: () => stderrChunks.join(""),
+  };
+}
+
+function invokeWriteCallback(encoding, callback) {
+  if (typeof encoding === "function") {
+    encoding();
+  } else if (typeof callback === "function") {
+    callback();
+  }
+}
+
+async function drainAsyncOutput() {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await new Promise((resolve) => setImmediate(resolve));
+}
+
+function writeRunnerStdout(text) {
+  (activeOutputCapture?.originalStdoutWrite ?? process.stdout.write.bind(process.stdout))(text);
+}
+
+function writeRunnerStderr(text) {
+  (activeOutputCapture?.originalStderrWrite ?? process.stderr.write.bind(process.stderr))(text);
+}

package/src/runtime-capture-report.js

@@ -71,13 +71,20 @@ export function renderRuntimeCaptureMarkdown(captureReport, options = {}) {
         result.fixture,
         result.status,
         result.entrypoint,
-        (result.captured ?? []).map((item) => `${item.kind}:${item.name}`).join(", ") || result.error || "-",
+        (result.captured ?? []).map((item) => `${item.kind}:${item.name}`).join(", ") || formatCaptureError(result),
       ]),
       ["Fixture", "Status", "Entrypoint", "Captured"],
     ),
   ].join("\n");
 }
 
+function formatCaptureError(result) {
+  if (!result.error) {
+    return "-";
+  }
+  return result.failureClass ? `${result.failureClass}: ${result.error}` : result.error;
+}
+
 function captureTargets(fixture, rootDir) {
   return fixture.packages.flatMap((packageSummary) => {
     const packageRoot = path.dirname(path.resolve(rootDir, packageSummary.path));
@@ -124,6 +131,9 @@ async function captureTarget(target, options) {
       packagePath: target.packagePath,
       entrypoint: target.entrypoint.relativePath,
       error: error.message,
+      ...(error.failureClass ? { failureClass: error.failureClass } : {}),
+      ...(error.missingExport ? { missingExport: error.missingExport } : {}),
+      ...(error.missingModule ? { missingModule: error.missingModule } : {}),
       captured: [],
     };
   }