@openclaw/plugin-inspector 0.1.0 → 0.1.2

package/src/capture-api.js

@@ -1,15 +1,68 @@
+export const defaultCaptureApiRegistrarProfiles = {
+  registerChannel: {
+    returnValue: ({ args }) => registrationObject(args, { id: "channel" }),
+  },
+  registerCli: {
+    returnValue: ({ args }) => registrationObject(args, { name: "cli" }),
+  },
+  registerCommand: {
+    returnValue: ({ args }) => registrationObject(args, { name: "command" }),
+  },
+  registerContextEngine: {
+    returnValue: ({ args }) => registrationObject(args, { id: "context-engine" }),
+  },
+  registerGatewayMethod: {
+    returnValue: ({ args }) => registrationObject(args, { name: "gateway.method" }),
+  },
+  registerHook: {
+    returnValue: ({ api }) => api,
+  },
+  registerHttpRoute: {
+    returnValue: ({ args }) => ({
+      ...registrationObject(args, { method: "GET", path: "/" }),
+      unregister() {},
+    }),
+  },
+  registerInteractiveHandler: {
+    returnValue: ({ args }) => registrationObject(args, { id: "interactive-handler" }),
+  },
+  registerMemoryPromptSection: {
+    returnValue: ({ args }) => registrationObject(args, { id: "memory-prompt-section" }),
+  },
+  registerMemoryRuntime: {
+    returnValue: ({ args }) => registrationObject(args, { id: "memory-runtime" }),
+  },
+  registerProvider: {
+    returnValue: ({ args }) => registrationObject(args, { id: "provider" }),
+  },
+  registerService: {
+    returnValue: ({ args }) => ({
+      ...registrationObject(args, { name: "service" }),
+      start: async () => undefined,
+      stop: async () => undefined,
+    }),
+  },
+  registerSpeechProvider: {
+    returnValue: ({ args }) => registrationObject(args, { id: "speech-provider" }),
+  },
+  registerTool: {
+    returnValue: ({ args }) => registrationObject(args, { name: "tool" }),
+  },
+};
+
 export function createCaptureApi(options = {}) {
   const captured = [];
   const retained = [];
-  const knownRegistrars = new Set(options.knownRegistrars ?? []);
+  const registrarProfiles = {
+    ...defaultCaptureApiRegistrarProfiles,
+    ...(options.registrarProfiles ?? {}),
+  };
+  const knownRegistrars = new Set(options.knownRegistrars ?? Object.keys(registrarProfiles));
   const retainHandlers = options.retainHandlers === true;
 
   const api = new Proxy(
     {
-      config: options.config ?? {},
-      logger: options.logger ?? console,
-      pluginConfig: options.pluginConfig ?? {},
-      runtime: options.runtime ?? {},
+      ...createCaptureContext(options),
       on(name, handler) {
         const captureIndex =
           captured.push({
@@ -42,6 +95,7 @@ export function createCaptureApi(options = {}) {
         }
         if (typeof property === "string" && isRegistrarProperty(property)) {
           return (...args) => {
+            const returnValue = registrationReturnValue(property, args, { api, registrarProfiles });
             const captureIndex =
               captured.push({
                 kind: "registration",
@@ -54,10 +108,11 @@ export function createCaptureApi(options = {}) {
                 kind: "registration",
                 name: property,
                 arguments: args,
+                returnValue,
                 captureIndex,
               });
             }
-            return registrationReturnValue(property, args);
+            return returnValue;
           };
         }
         return undefined;
@@ -68,19 +123,122 @@ export function createCaptureApi(options = {}) {
   return api;
 }
 
+export function createCaptureContext(options = {}) {
+  return {
+    config: options.config ?? {},
+    logger: options.logger ?? console,
+    pluginConfig: options.pluginConfig ?? {},
+    runtime: options.runtime ?? createRuntimeContext(options),
+    secrets: options.secrets ?? createSecretContext(options),
+    store: options.store ?? createStoreContext(options),
+    paths: options.paths ?? {
+      cacheDir: ".plugin-inspector/cache",
+      configDir: ".plugin-inspector/config",
+      dataDir: ".plugin-inspector/data",
+    },
+    agent: options.agent ?? {
+      id: "plugin-inspector-agent",
+      accountId: "default",
+    },
+    gateway: options.gateway ?? {
+      baseUrl: "http://127.0.0.1:0",
+      registerRoute(route) {
+        return {
+          ...route,
+          unregister() {},
+        };
+      },
+    },
+    fetch: options.fetch ?? (async () => ({ ok: true, status: 200, json: async () => ({}), text: async () => "" })),
+  };
+}
+
 function isRegistrarProperty(property) {
   return property.startsWith("register") || property.startsWith("define");
 }
 
-function registrationReturnValue(name, args) {
-  if (name === "registerService") {
+function registrationReturnValue(name, args, context) {
+  const profile = context.registrarProfiles[name];
+  if (profile?.returnValue) {
+    return profile.returnValue({ name, args, api: context.api });
+  }
+  return registrationObject(args, {});
+}
+
+function createRuntimeContext(options) {
+  const runtime = options.runtime ?? {};
+  return {
+    ...runtime,
+    agent: runtime.agent ?? {},
+    env: options.env ?? {},
+    logger: options.logger ?? console,
+    now: () => new Date(0),
+    tts: runtime.tts ?? {},
+    state: {
+      resolveStateDir: () => options.stateDir ?? process.cwd(),
+      ...(runtime.state ?? {}),
+    },
+  };
+}
+
+function createSecretContext(options) {
+  const secrets = new Map(Object.entries(options.secretValues ?? {}));
+  return {
+    async get(name) {
+      return secrets.get(name) ?? null;
+    },
+    async has(name) {
+      return secrets.has(name);
+    },
+    async require(name) {
+      if (!secrets.has(name)) {
+        throw new Error(`Missing mocked secret: ${name}`);
+      }
+      return secrets.get(name);
+    },
+    async resolve(value) {
+      return typeof value === "string" && value.startsWith("secret:") ? (secrets.get(value.slice(7)) ?? null) : value;
+    },
+  };
+}
+
+function createStoreContext() {
+  const values = new Map();
+  return {
+    async delete(key) {
+      return values.delete(key);
+    },
+    async get(key) {
+      return values.get(key);
+    },
+    async list() {
+      return [...values.keys()].sort();
+    },
+    async set(key, value) {
+      values.set(key, value);
+      return value;
+    },
+  };
+}
+
+function registrationObject(args, defaults) {
+  const first = args[0];
+  if (first && typeof first === "object") {
     return {
-      name: objectName(args[0]),
-      start: async () => undefined,
-      stop: async () => undefined,
+      ...defaults,
+      ...first,
+      name: objectName(first) ?? defaults.name,
+      id: objectId(first) ?? defaults.id,
     };
   }
-  return objectName(args[0]) ?? undefined;
+  if (typeof first === "string") {
+    return {
+      ...defaults,
+      name: first,
+      id: defaults.id,
+    };
+  }
+  return { ...defaults };
 }
 
 function summarizeArguments(args) {
@@ -113,3 +271,13 @@ function objectName(value) {
   }
   return typeof value.id === "string" ? value.id : null;
 }
+
+function objectId(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  if (typeof value.id === "string") {
+    return value.id;
+  }
+  return typeof value.name === "string" ? value.name : null;
+}

package/src/cli.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 import {
-  buildRuntimeCaptureReport,
+  renderTextSummary,
+  runPluginCheck,
+} from "./index.js";
+import {
   captureEntrypoint,
-  inspectCompatibilityFixtureSet,
   inspectFixtureSet,
   loadInspectorConfig,
-  loadPluginRootConfig,
-  renderTextSummary,
+  writePluginInspectorInit,
   writeArtifacts,
-  writeCompatibilityReport,
   writeReport,
-  writeRuntimeCaptureReport,
-} from "./index.js";
+} from "./advanced.js";
 
 const args = process.argv.slice(2);
 const command = args[0]?.startsWith("-") ? "check" : (args[0] ?? "check");
@@ -22,6 +21,8 @@ try {
     printHelp();
   } else if (command === "check") {
     await runCheck(commandArgs);
+  } else if (command === "init") {
+    await runInit(commandArgs);
   } else if (command === "inspect" || command === "report" || command === "ci") {
     await runReport(command, commandArgs);
   } else if (command === "capture") {
@@ -36,26 +37,13 @@ try {
 
 async function runCheck(commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   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`);
-    }
-  }
+  const capture = readRuntimeFlag(commandArgs);
+  const mockSdk = readMockSdkFlag(commandArgs);
+  const { report } = await runPluginCheck({ configPath, pluginRoot, outDir, openclawPath, capture, mockSdk });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));
@@ -68,6 +56,25 @@ async function runCheck(commandArgs) {
   }
 }
 
+async function runInit(commandArgs) {
+  const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
+  const configPath = readFlag(commandArgs, "--config") ?? undefined;
+  const workflowPath = readFlag(commandArgs, "--workflow") ?? undefined;
+  const packageManager = readFlag(commandArgs, "--package-manager") ?? "npm";
+  const result = await writePluginInspectorInit({
+    pluginRoot,
+    configPath,
+    workflowPath,
+    packageManager,
+    ci: commandArgs.includes("--ci"),
+    force: commandArgs.includes("--force"),
+  });
+
+  for (const filePath of result.written) {
+    console.log(`wrote ${filePath}`);
+  }
+}
+
 async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
@@ -92,7 +99,7 @@ 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");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? commandArgs.includes("--mock-sdk");
   if (!entrypoint) {
     throw new Error("capture requires an entrypoint path");
   }
@@ -117,14 +124,49 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function readRuntimeFlag(commandArgs) {
+  if (commandArgs.includes("--runtime") || commandArgs.includes("--capture")) {
+    return true;
+  }
+  if (commandArgs.includes("--no-runtime") || commandArgs.includes("--no-capture")) {
+    return false;
+  }
+  return undefined;
+}
+
+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;
+}
+
 function printHelp() {
   console.log(`plugin-inspector
 
 Usage:
-  plugin-inspector check [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--capture] [--json]
+  plugin-inspector
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--json]
+  plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--package-manager npm|pnpm|yarn|bun] [--force]
   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>]
+  PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--plugin-root <path>] [--output <path>]
+
+Default check runs from the current plugin root and writes reports/ unless --out is set.
+Runtime capture is opt-in because it imports plugin code; use --runtime with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
 `);
 }

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

@@ -1,186 +1,11 @@
 export {
-  escapeMarkdownTableCell,
-  renderArtifactContent,
-  renderMarkdownTable,
-  renderPaddedMarkdownTable,
-  writeArtifacts,
-  writeJsonMarkdownArtifacts,
-} from "./artifacts.js";
-export {
-  normalizeRepoPath,
-  posixJoin,
-  resolveFromRoot,
-  resolveRequiredFromRoot,
-  slugForArtifact,
-  toRepoPath,
-} from "./path-utils.js";
-export { readJsonFile, readOptionalJsonFile } from "./json-file.js";
-export { assertRunCount, percentile } from "./stats.js";
-export { createCaptureApi } from "./capture-api.js";
-export {
-  buildCiPolicyReport,
-  defaultCiPolicyReportOptions,
-  renderCiPolicyMarkdown,
-  validateCiPolicy,
-  validateCiPolicyReport,
-  writeCiPolicyReport,
-} from "./ci-policy.js";
-export {
-  buildCiSummary,
-  defaultCiReportPaths,
-  deriveCiStatus,
-  readCiReports,
-  renderCiSummaryMarkdown,
-  writeCiSummary,
-} from "./ci-summary.js";
-export {
-  buildContractProbes,
-  contractProbeRules,
-  probePriority,
-} from "./contract-probes.js";
-export {
-  buildContractCapture,
-  defaultHookAssertions,
-  defaultHookContexts,
-  defaultHookEvents,
-  defaultRegistrationArguments,
-  defaultRegistrationAssertions,
-  renderContractCaptureMarkdown,
-  validateContractCapture,
-  writeContractCapture,
-} from "./contract-capture.js";
-export {
-  renderCompatibilityIssuesReport,
-  renderCompatibilityMarkdownReport,
-} from "./compatibility-report.js";
-export {
-  knownIssueClasses,
-  validateContractCoverage,
-} from "./contract-coverage.js";
-export {
-  buildColdImportReadiness,
-  renderColdImportReadinessMarkdown,
-  validateColdImportReadiness,
-  writeColdImportReadiness,
-} from "./cold-import-readiness.js";
-export {
-  buildIssues,
-  classifyIssueFinding,
-  deprecatedCompatRecords,
-  issueId,
-  issueMetadata,
-  issueMetadataByCode,
-  knownIssueCodes,
-  summarizeIssueClasses,
-} from "./issues.js";
-export {
-  buildExecutionResultsReport,
-  defaultExecutionResultsOptions,
-  renderExecutionResultsMarkdown,
-  writeExecutionResultsReport,
-} from "./execution-results.js";
-export {
-  buildCompatibilityFixtureReport,
-  classifyCompatibilityFixture,
-  classifyPackageContracts,
-  classifyTargetOpenClawCoverage,
-  readPackageSummaries,
-  readPluginManifests,
-  summarizePackage,
-} from "./fixture-summary.js";
-export {
-  buildImportLoopProfile,
-  defaultImportLoopProfileOptions,
-  renderImportLoopProfileMarkdown,
-  validateImportLoopProfile,
-  writeImportLoopProfile,
-} from "./import-loop-profile.js";
-export {
-  defaultOpenClawCheckoutPaths,
-  openClawTargetPathCandidates,
-  parseCompatRecordEntries,
-  parseExportedStringArray,
-  parsePluginSdkExports,
-  parseTypeFields,
-  readOpenClawTargetSurface,
-} from "./openclaw-target.js";
-export {
-  captureEntrypoint,
-  captureEntrypointWithMockSdk,
-  inspectCompatibilityFixtureSet,
-  inspectFixtureSet,
-  inspectPlugin,
-  inspectSourceText,
-} from "./inspector.js";
-export {
-  defaultPluginRootConfigFiles,
-  fixtureCheckoutPath,
-  fixtureSourceRoot,
-  loadInspectorConfig,
-  loadPluginRootConfig,
-  normalizeInspectorConfig,
-  normalizePluginRootConfig,
-  validateInspectorConfig,
-} from "./config.js";
-export {
-  buildPlatformProbes,
-  defaultPlatformTargets,
-  renderPlatformProbesMarkdown,
-  validatePlatformProbes,
-  writePlatformProbes,
-} from "./platform-probes.js";
-export {
-  buildProfileDiff,
-  defaultProfileDiffOptions,
-  renderProfileDiffMarkdown,
-  validateProfileDiff,
-  writeProfileDiff,
-} from "./profile-diff.js";
-export {
-  buildRefDiff,
-  defaultRefDiffDimensions,
-  defaultRefDiffOptions,
-  renderRefDiffMarkdown,
-  validateRefDiff,
-  writeRefDiff,
-} from "./ref-diff.js";
-export {
-  buildCompatibilityReport,
-  classifyCompatRecordCoverage,
-  renderMarkdownReport,
+  capturePluginEntrypoint,
+  createCaptureApi,
+  inspectFixtureSetConfig,
+  inspectPluginRoot,
+  loadPluginConfig,
   renderTextSummary,
-  writeCompatibilityReport,
-  writeReport,
-} from "./report.js";
-export {
-  buildRuntimeProfile,
-  defaultRuntimeProfileCommands,
-  defaultRuntimeProfileOptions,
-  renderRuntimeProfileMarkdown,
-  validateRuntimeProfile,
-  writeRuntimeProfile,
-} from "./runtime-profile.js";
-export {
-  buildRuntimeCaptureReport,
-  renderRuntimeCaptureMarkdown,
-  writeRuntimeCaptureReport,
-} from "./runtime-capture-report.js";
-export { createMockSdkPackage } from "./sdk-mock.js";
-export {
-  buildSyntheticProbePlan,
-  defaultSyntheticHookContexts,
-  defaultSyntheticHookEvents,
-  defaultSyntheticRegistrationArguments,
-  renderSyntheticProbeMarkdown,
-  runCapturedSyntheticProbes,
-  syntheticRegistrationExecutionProfiles,
-  validateSyntheticProbePlan,
-  writeSyntheticProbePlan,
-} from "./synthetic-probes.js";
-export {
-  buildWorkspacePlan,
-  defaultWorkspacePlanOptions,
-  renderWorkspacePlanMarkdown,
-  validateWorkspacePlan,
-  writeWorkspacePlan,
-} from "./workspace-plan.js";
+  runPluginCheck,
+  setupPluginInspector,
+  writePluginReports,
+} from "./api.js";