@openclaw/plugin-inspector 0.1.1 → 0.1.3

package/src/synthetic-probes-cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+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";
+import { captureEntrypoint, runCapturedSyntheticProbes, writeArtifacts } from "./advanced.js";
+import { createMockSdkPackage } from "./sdk-mock.js";
+
+const args = process.argv.slice(2);
+
+try {
+  await run(args);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+
+async function run(commandArgs) {
+  const entrypoint = readFlag(commandArgs, "--entrypoint") ?? commandArgs.find((arg) => !arg.startsWith("-"));
+  const outputPath = readFlag(commandArgs, "--output");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root");
+  const includeLifecycle = commandArgs.includes("--include-lifecycle");
+  const includeChannelRuntime = commandArgs.includes("--include-channel-runtime");
+  const includeProviderCapabilities = commandArgs.includes("--include-provider-capabilities");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? true;
+
+  if (!entrypoint) {
+    throw new Error("synthetic probes require --entrypoint <path>");
+  }
+  if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+    throw new Error("synthetic probes import plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+  }
+
+  const capture = await captureForSyntheticProbes(entrypoint, {
+    mockSdk,
+    pluginRoot,
+    apiOptions: { retainHandlers: true },
+  });
+  const results = await runCapturedSyntheticProbes(capture, {
+    includeLifecycle,
+    includeChannelRuntime,
+    includeProviderCapabilities,
+  });
+  const json = `${JSON.stringify(results, null, 2)}\n`;
+
+  if (outputPath) {
+    await writeArtifacts([{ path: outputPath, content: json }]);
+  } else {
+    process.stdout.write(json);
+  }
+}
+
+async function captureForSyntheticProbes(entrypoint, options) {
+  if (options.mockSdk !== true) {
+    return captureEntrypoint(entrypoint, options);
+  }
+
+  const resolvedEntrypoint = path.resolve(process.cwd(), entrypoint);
+  const pluginRoot = path.resolve(process.cwd(), options.pluginRoot ?? path.dirname(resolvedEntrypoint));
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-synthetic-mock-sdk-"));
+  try {
+    const { loaderPath } = await createMockSdkPackage(workspace, { pluginRoot });
+    register(pathToFileURL(loaderPath));
+    return captureEntrypoint(entrypoint, {
+      ...options,
+      mockSdk: false,
+      pluginRoot,
+    });
+  } finally {
+    await rm(workspace, { force: true, recursive: true });
+  }
+}
+
+function readFlag(commandArgs, name) {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) {
+    return null;
+  }
+  return commandArgs[index + 1] ?? null;
+}
+
+function readMockSdkFlag(commandArgs) {
+  const sdk = readFlag(commandArgs, "--sdk");
+  if (sdk === "mock") {
+    return true;
+  }
+  if (sdk === "real") {
+    return false;
+  }
+  if (sdk && !["mock", "real"].includes(sdk)) {
+    throw new Error("--sdk must be mock or real");
+  }
+  if (commandArgs.includes("--mock-sdk")) {
+    return true;
+  }
+  if (commandArgs.includes("--real-sdk")) {
+    return false;
+  }
+  return undefined;
+}

package/src/synthetic-probes.js

@@ -203,6 +203,47 @@ export const defaultSyntheticRegistrationArguments = {
   registerTool: [{ name: "fixture_tool", inputSchema: { type: "object", properties: {} }, run: "function" }],
 };
 
+export const defaultSyntheticRegistrationProbeInputs = {
+  registerCli: {
+    execute: commandProbeArgs,
+    handler: commandProbeArgs,
+    run: commandProbeArgs,
+  },
+  registerCommand: {
+    execute: commandProbeArgs,
+    handler: commandProbeArgs,
+    run: commandProbeArgs,
+  },
+  registerGatewayMethod: {
+    execute: gatewayProbeArgs,
+    handler: gatewayProbeArgs,
+    run: gatewayProbeArgs,
+  },
+  registerHttpRoute: {
+    execute: httpRouteProbeArgs,
+    handler: httpRouteProbeArgs,
+    run: httpRouteProbeArgs,
+  },
+  registerInteractiveHandler: {
+    execute: interactiveProbeArgs,
+    handler: interactiveProbeArgs,
+    run: interactiveProbeArgs,
+  },
+  registerService: {
+    start: lifecycleProbeArgs,
+    stop: lifecycleProbeArgs,
+  },
+  registerSpeechProvider: {
+    speak: speechProbeArgs,
+    synthesize: speechProbeArgs,
+  },
+  registerTool: {
+    execute: toolExecuteProbeArgs,
+    handler: toolRunProbeArgs,
+    run: toolRunProbeArgs,
+  },
+};
+
 export function buildSyntheticProbePlan(options = {}) {
   if (!options.capture) {
     throw new TypeError("buildSyntheticProbePlan requires a capture inventory");
@@ -411,7 +452,7 @@ async function runRegistrationProbes(entry, retainedEntry, captureIndex, options
     return [metadataOnlyResult(entry, captureIndex, profile.reason)];
   }
 
-  const descriptor = retainedEntry.arguments?.[0];
+  const descriptor = retainedEntry.arguments?.[0] ?? retainedEntry.returnValue;
   if (!descriptor || typeof descriptor !== "object") {
     return [blockedResult(entry, captureIndex, "captured registration has no object descriptor")];
   }
@@ -419,7 +460,7 @@ async function runRegistrationProbes(entry, retainedEntry, captureIndex, options
     return [blockedResult(entry, captureIndex, `captured registration requires ${profile.option}=true`)];
   }
 
-  const invocations = registrationInvocations(entry.name, descriptor, profile, options);
+  const invocations = registrationInvocations(entry.name, descriptor, retainedEntry.returnValue, profile, options);
   if (invocations.length === 0) {
     return [blockedResult(entry, captureIndex, "captured registration has no supported callable probe")];
   }
@@ -437,14 +478,21 @@ async function runRegistrationProbes(entry, retainedEntry, captureIndex, options
   );
 }
 
-function registrationInvocations(registrar, descriptor, profile, options) {
+function registrationInvocations(registrar, descriptor, returnValue, profile, options) {
   const invocations = [];
+  const allowReturnValueFallback = descriptor === returnValue;
 
   for (const property of profile.callableProperties) {
-    if (typeof descriptor[property] === "function") {
+    const callable =
+      typeof descriptor[property] === "function"
+        ? descriptor[property]
+        : allowReturnValueFallback
+          ? returnValue?.[property]
+          : undefined;
+    if (typeof callable === "function") {
       invocations.push({
         label: `${registrar}.${property}`,
-        invoke: () => invokeRegistrationCallable(descriptor[property], registrar, property, options),
+        invoke: () => invokeRegistrationCallable(callable, registrar, property, options),
       });
     }
   }
@@ -453,10 +501,9 @@ function registrationInvocations(registrar, descriptor, profile, options) {
 
 function invokeRegistrationCallable(callable, registrar, property, options) {
   const event = syntheticRegistrationEvent(registrar, property, options);
-  if (property === "execute") {
-    return callable("call-fixture", event.params, new AbortController().signal, () => undefined);
-  }
-  return callable(event);
+  const inputFactory = options.registrationProbeInputs?.[registrar]?.[property] ?? defaultSyntheticRegistrationProbeInputs[registrar]?.[property];
+  const args = inputFactory ? inputFactory(event, options) : [event];
+  return callable(...args);
 }
 
 function syntheticRegistrationEvent(registrar, property, options) {
@@ -478,6 +525,103 @@ function syntheticRegistrationEvent(registrar, property, options) {
   };
 }
 
+function toolRunProbeArgs(event) {
+  return [
+    event.params,
+    {
+      source: event.source,
+      toolName: event.toolName,
+      toolCallId: event.toolCall.id,
+      signal: new AbortController().signal,
+      logger: console,
+    },
+  ];
+}
+
+function toolExecuteProbeArgs(event) {
+  return [event.toolCall.id, event.params, new AbortController().signal, () => undefined];
+}
+
+function httpRouteProbeArgs(event) {
+  return [
+    {
+      method: "POST",
+      path: "/fixture/probe",
+      url: "http://127.0.0.1/fixture/probe",
+      headers: event.headers,
+      body: event.body,
+      json: async () => event.body,
+      text: async () => JSON.stringify(event.body),
+    },
+    {
+      source: event.source,
+      params: event.params,
+      logger: console,
+    },
+  ];
+}
+
+function commandProbeArgs(event) {
+  return [
+    event.input,
+    {
+      source: event.source,
+      signal: new AbortController().signal,
+      logger: console,
+    },
+  ];
+}
+
+function gatewayProbeArgs(event) {
+  return [
+    {
+      params: event.params,
+      body: event.body,
+      headers: event.headers,
+    },
+    {
+      source: event.source,
+      logger: console,
+    },
+  ];
+}
+
+function interactiveProbeArgs(event) {
+  return [
+    {
+      id: "interaction-fixture",
+      payload: event.body,
+    },
+    {
+      source: event.source,
+      logger: console,
+    },
+  ];
+}
+
+function lifecycleProbeArgs(event) {
+  return [
+    {
+      source: event.source,
+      logger: console,
+      signal: new AbortController().signal,
+    },
+  ];
+}
+
+function speechProbeArgs(event) {
+  return [
+    {
+      text: "fixture speech request",
+      voice: "fixture",
+    },
+    {
+      source: event.source,
+      logger: console,
+    },
+  ];
+}
+
 async function runProbe({ captureIndex, kind, seam, label, invoke }) {
   try {
     const output = await invoke();

package/src/workspace-plan.js

@@ -1,15 +1,16 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
 import { buildColdImportReadiness } from "./cold-import-readiness.js";
 import { normalizeRepoPath, posixJoin, slugForArtifact } from "./path-utils.js";
 
 export const defaultWorkspacePlanOptions = {
-  captureScript: "plugin-inspector-capture",
+  captureScript: null,
   optInEnv: "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1",
   resultsRoot: ".plugin-inspector/results",
-  syntheticProbeScript: "plugin-inspector-synthetic-probes",
+  syntheticProbeScript: null,
   workspaceRoot: ".plugin-inspector/workspaces",
 };
 
@@ -450,12 +451,23 @@ function runCommand(packageManager, script) {
 
 function captureCommand(settings, fixtureId, entrypoint, workspacePath) {
   const loader = entrypoint.blockers.some((blocker) => blocker.code === "ts-loader-required") ? " --import tsx" : "";
-  return `${settings.optInEnv} node${loader} ${settings.captureScript} ${entrypoint.specifier} --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture")}`;
+  const script = helperScript(settings, workspacePath, settings.captureScript, "capture-cli.js");
+  return `${settings.optInEnv} node${loader} ${script} ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture")}`;
 }
 
 function syntheticProbeCommand(settings, fixtureId, entrypoint, workspacePath) {
   const loader = entrypoint.blockers.some((blocker) => blocker.code === "ts-loader-required") ? " --import tsx" : "";
-  return `${settings.optInEnv} node${loader} ${settings.syntheticProbeScript} --entrypoint ${entrypoint.specifier} --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic")}`;
+  const script = helperScript(settings, workspacePath, settings.syntheticProbeScript, "synthetic-probes-cli.js");
+  return `${settings.optInEnv} node${loader} ${script} --entrypoint ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic")}`;
+}
+
+function helperScript(settings, workspacePath, configuredScript, helperFileName) {
+  if (configuredScript) {
+    return configuredScript;
+  }
+  const helperPath = fileURLToPath(new URL(`./${helperFileName}`, import.meta.url));
+  const workspaceFsPath = path.join(settings.rootDir, workspacePath);
+  return repoRelative(path.relative(workspaceFsPath, helperPath));
 }
 
 function targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath) {