@openclaw/plugin-inspector 0.1.2 → 0.2.0

package/src/cli.js

@@ -1,12 +1,21 @@
 #!/usr/bin/env node
+import path from "node:path";
 import {
+  loadPluginConfig,
   renderTextSummary,
   runPluginCheck,
 } from "./index.js";
 import {
+  buildCiSummary,
   captureEntrypoint,
+  defaultJunitPath,
+  defaultSarifPath,
+  inspectCompatibilityFixtureSet,
   inspectFixtureSet,
   loadInspectorConfig,
+  writeCiOutputArtifacts,
+  writeCiSummary,
+  writeCompatibilityReport,
   writePluginInspectorInit,
   writeArtifacts,
   writeReport,
@@ -23,8 +32,16 @@ try {
     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 === "config") {
+    await runConfig(commandArgs);
+  } else if (command === "inspect" || command === "report") {
+    if (command === "inspect" && !commandArgs.includes("--config")) {
+      await runCheck(commandArgs);
+    } else {
+      await runReport(command, commandArgs);
+    }
+  } else if (command === "ci") {
+    await runCi(commandArgs);
   } else if (command === "capture") {
     await runCapture(commandArgs);
   } else {
@@ -35,6 +52,18 @@ try {
   process.exitCode = 1;
 }
 
+async function runConfig(commandArgs) {
+  const configPath = readFlag(commandArgs, "--config");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
+  const config = await loadPluginConfig({ configPath, pluginRoot });
+
+  if (commandArgs.includes("--json")) {
+    console.log(JSON.stringify(config, null, 2));
+  } else {
+    console.log(renderConfigTextSummary(config));
+  }
+}
+
 async function runCheck(commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
@@ -43,7 +72,13 @@ async function runCheck(commandArgs) {
   const json = commandArgs.includes("--json");
   const capture = readRuntimeFlag(commandArgs);
   const mockSdk = readMockSdkFlag(commandArgs);
-  const { report } = await runPluginCheck({ configPath, pluginRoot, outDir, openclawPath, capture, mockSdk });
+  const ciOutputs = readCiOutputFlags(commandArgs);
+  const { report, paths } = await runPluginCheck({ configPath, pluginRoot, outDir, openclawPath, capture, mockSdk });
+  await writeCiOutputArtifacts(report, {
+    ...ciOutputs,
+    cwd: path.dirname(paths.jsonPath),
+    outDir: ".",
+  });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));
@@ -80,9 +115,15 @@ async function runReport(command, commandArgs) {
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
+  const ciOutputs = readCiOutputFlags(commandArgs);
   const config = await loadInspectorConfig(configPath);
   const report = await inspectFixtureSet(config);
-  await writeReport(report, { outDir });
+  const paths = await writeReport(report, { outDir });
+  await writeCiOutputArtifacts(report, {
+    ...ciOutputs,
+    cwd: path.dirname(paths.jsonPath),
+    outDir: ".",
+  });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));
@@ -95,6 +136,72 @@ async function runReport(command, commandArgs) {
   }
 }
 
+async function runCi(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 = readRuntimeFlag(commandArgs);
+  const mockSdk = readMockSdkFlag(commandArgs);
+  const ciOutputs = readCiOutputFlags(commandArgs, { defaultEnabled: true });
+  const { report, reportDir } = await runCiCompatibilityReport({
+    capture,
+    configPath,
+    mockSdk,
+    openclawPath,
+    outDir,
+    pluginRoot,
+  });
+
+  const summary = await buildCiSummary({
+    artifactBaseDir: reportDir,
+    reportPaths: {
+      compatibility: "plugin-inspector-report.json",
+    },
+    reports: {
+      compatibility: report,
+    },
+  });
+  await writeCiSummary(summary, {
+    jsonPath: path.join(reportDir, "plugin-inspector-ci-summary.json"),
+    markdownPath: path.join(reportDir, "plugin-inspector-ci-summary.md"),
+  });
+  await writeCiOutputArtifacts(report, {
+    ...ciOutputs,
+    cwd: reportDir,
+    outDir: ".",
+  });
+
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(renderCiTextSummary(summary));
+  }
+
+  if (summary.status !== "pass") {
+    throw new Error("plugin-inspector ci summary failed");
+  }
+}
+
+async function runCiCompatibilityReport({ capture, configPath, mockSdk, openclawPath, outDir, pluginRoot }) {
+  if (configPath) {
+    const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
+    const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
+    await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
+    return {
+      report,
+      reportDir: path.resolve(config.rootDir, outDir),
+    };
+  }
+
+  const { report } = await runPluginCheck({ pluginRoot, outDir, openclawPath, capture, mockSdk });
+  return {
+    report,
+    reportDir: path.resolve(pluginRoot ?? process.cwd(), outDir),
+  };
+}
+
 async function runCapture(commandArgs) {
   const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
   const outputPath = readFlag(commandArgs, "--output");
@@ -124,6 +231,26 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function readOptionalPathFlag(commandArgs, name, defaultPath) {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) {
+    return null;
+  }
+  const value = commandArgs[index + 1];
+  return value && !value.startsWith("-") ? value : defaultPath;
+}
+
+function readCiOutputFlags(commandArgs, options = {}) {
+  return {
+    sarifPath: commandArgs.includes("--no-sarif")
+      ? null
+      : (readOptionalPathFlag(commandArgs, "--sarif", defaultSarifPath) ?? (options.defaultEnabled ? defaultSarifPath : null)),
+    junitPath: commandArgs.includes("--no-junit")
+      ? null
+      : (readOptionalPathFlag(commandArgs, "--junit", defaultJunitPath) ?? (options.defaultEnabled ? defaultJunitPath : null)),
+  };
+}
+
 function readRuntimeFlag(commandArgs) {
   if (commandArgs.includes("--runtime") || commandArgs.includes("--capture")) {
     return true;
@@ -154,19 +281,43 @@ function readMockSdkFlag(commandArgs) {
   return undefined;
 }
 
+function renderCiTextSummary(summary) {
+  return [
+    `Status: ${summary.status.toUpperCase()}`,
+    `Breakages: ${summary.summary.breakages}`,
+    `Issues: ${summary.summary.issues}`,
+    `Artifacts: ${Object.values(summary.artifacts).filter(Boolean).length}`,
+  ].join("\n");
+}
+
+function renderConfigTextSummary(config) {
+  const fixture = config.fixtures[0];
+  return [
+    `Plugin: ${fixture.id}`,
+    `Root: ${config.rootDir}`,
+    `Config: ${config.configPath ?? "auto"}`,
+    `Priority: ${fixture.priority}`,
+    `Seams: ${fixture.seams.join(", ")}`,
+    `Runtime capture: ${config.capture?.runtime === true ? "on" : "off"}`,
+    `Mock SDK: ${config.capture?.mockSdk === false ? "off" : "on"}`,
+  ].join("\n");
+}
+
 function printHelp() {
   console.log(`plugin-inspector
 
 Usage:
   plugin-inspector
   plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--json]
+  plugin-inspector config [--plugin-root <path>] [--config <path>] [--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 inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--check] [--json] [--sarif [path]] [--junit [path]]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--json] [--no-sarif] [--no-junit]
   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.
+CI writes SARIF and JUnit artifacts by default; check/inspect can write them with --sarif and --junit.
 Runtime capture is opt-in because it imports plugin code; use --runtime with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
 `);
 }

package/src/config.js

@@ -4,6 +4,7 @@ import path from "node:path";
 
 export const npmPackagePayloadDir = ".crabpot-package";
 export const defaultPluginRootConfigFiles = ["plugin-inspector.config.json", ".plugin-inspector.json"];
+export const packageJsonConfigKeys = ["pluginInspector", "plugin-inspector"];
 
 export async function loadInspectorConfig(configPath, options = {}) {
   if (!configPath) {
@@ -24,16 +25,23 @@ export async function loadInspectorConfig(configPath, options = {}) {
 export async function loadPluginRootConfig(configPath = null, options = {}) {
   const rootDir = path.resolve(options.cwd ?? process.cwd());
   const resolvedPath = configPath ? path.resolve(rootDir, configPath) : findPluginRootConfigPath(rootDir);
-  if (!resolvedPath && !existsSync(path.join(rootDir, "package.json")) && !existsSync(path.join(rootDir, "openclaw.plugin.json"))) {
+  const packageJsonPath = path.join(rootDir, "package.json");
+  const packageJson = await readJsonIfExists(packageJsonPath);
+  const packageConfig = packageJsonConfig(packageJson);
+
+  if (!resolvedPath && !packageJson && !existsSync(path.join(rootDir, "openclaw.plugin.json"))) {
     throw new Error("run from a plugin root with package.json/openclaw.plugin.json, or pass --config");
   }
-  const config = resolvedPath ? JSON.parse(await readFile(resolvedPath, "utf8")) : { version: 1 };
+
+  const config = resolvedPath
+    ? JSON.parse(await readFile(resolvedPath, "utf8"))
+    : (packageConfig.config ?? { version: 1 });
   const normalizedConfig = await normalizePluginRootConfig(config, { rootDir });
   validateInspectorConfig(normalizedConfig);
   return {
     ...normalizedConfig,
     rootDir,
-    configPath: resolvedPath,
+    configPath: resolvedPath ?? packageConfig.configPath,
   };
 }
 
@@ -164,6 +172,25 @@ function findPluginRootConfigPath(rootDir) {
   return defaultPluginRootConfigFiles.map((file) => path.join(rootDir, file)).find(existsSync) ?? null;
 }
 
+function packageJsonConfig(packageJson) {
+  if (!packageJson) {
+    return { config: null, configPath: null };
+  }
+  for (const key of packageJsonConfigKeys) {
+    if (packageJson[key] === undefined) {
+      continue;
+    }
+    if (!packageJson[key] || typeof packageJson[key] !== "object" || Array.isArray(packageJson[key])) {
+      throw new Error(`package.json ${key} must be an object`);
+    }
+    return {
+      config: packageJson[key],
+      configPath: `package.json#${key}`,
+    };
+  }
+  return { config: null, configPath: null };
+}
+
 async function readJsonIfExists(filePath) {
   if (!existsSync(filePath)) {
     return null;

package/src/contract-probes.js

@@ -29,6 +29,11 @@ export const contractProbeRules = {
     contract: "Every observed OpenClaw plugin SDK import remains exported by the target OpenClaw package.",
     target: "sdk-alias",
   },
+  "reserved-sdk-import": {
+    id: "sdk.import.reserved-bundled-plugin-boundary",
+    contract: "External plugins use documented public SDK subpaths instead of reserved bundled-plugin compatibility shims.",
+    target: "sdk-import",
+  },
   "provider-auth-env-vars": {
     id: "manifest.compat.provider-auth-env-vars",
     contract: "Legacy provider auth env metadata continues to map into config/help surfaces.",

package/src/fixture-summary.js

@@ -626,7 +626,12 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
 
   const sdkExports = new Set(targetOpenClaw.sdkExports);
   const unknownImports = fixtureReport.sdkImportDetails.filter((sdkImport) => !sdkExports.has(sdkImport.specifier));
-  if (unknownImports.length === 0) {
+  const reservedSdkExports = new Set(targetOpenClaw.reservedSdkExports ?? []);
+  const reservedImports = fixtureReport.sdkImportDetails.filter((sdkImport) =>
+    reservedSdkExports.has(sdkImport.specifier),
+  );
+
+  if (reservedImports.length === 0 && unknownImports.length === 0) {
     logs.push({
       fixture: fixture.id,
       code: "sdk-exports-present",
@@ -637,21 +642,40 @@ function classifySdkImportCoverage({ fixture, fixtureReport, targetOpenClaw, war
     return;
   }
 
-  warnings.push({
-    fixture: fixture.id,
-    code: "sdk-export-missing",
-    level: "warning",
-    message: "fixture imports plugin SDK aliases that are not exported by the target OpenClaw package",
-    evidence: detailEvidence(unknownImports, "specifier"),
-    compatRecord: "plugin-sdk-export-aliases",
-  });
-  decisions.push({
-    fixture: fixture.id,
-    decision: "core-compat-adapter",
-    seam: "sdk-alias",
-    action: "Restore the package export alias or publish a versioned migration map before cold-importing old plugins.",
-    evidence: unique(unknownImports.map((sdkImport) => sdkImport.specifier)).join(", "),
-  });
+  if (unknownImports.length > 0) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "sdk-export-missing",
+      level: "warning",
+      message: "fixture imports plugin SDK aliases that are not exported by the target OpenClaw package",
+      evidence: detailEvidence(unknownImports, "specifier"),
+      compatRecord: "plugin-sdk-export-aliases",
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "core-compat-adapter",
+      seam: "sdk-alias",
+      action: "Restore the package export alias or publish a versioned migration map before cold-importing old plugins.",
+      evidence: unique(unknownImports.map((sdkImport) => sdkImport.specifier)).join(", "),
+    });
+  }
+
+  if (reservedImports.length > 0) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "reserved-sdk-import",
+      level: "warning",
+      message: "fixture imports reserved bundled-plugin SDK compatibility subpaths",
+      evidence: detailEvidence(reservedImports, "specifier"),
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "sdk-import",
+      action: "Move the plugin to documented public SDK subpaths or plugin-local helpers before relying on this compatibility shim.",
+      evidence: unique(reservedImports.map((sdkImport) => sdkImport.specifier)).join(", "),
+    });
+  }
 }
 
 function classifyManifestFieldCoverage({ fixture, fixtureReport, targetOpenClaw, warnings, logs, decisions }) {

package/src/index.js

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

package/src/init.js

@@ -79,8 +79,7 @@ jobs:
           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
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 ${setup.exec} @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk
       - uses: actions/upload-artifact@v5
         if: always()
         with:

package/src/issues.js

@@ -32,6 +32,7 @@ export const knownIssueCodes = new Set([
   "provider-auth-env-vars",
   "registration-capture-gap",
   "runtime-tool-capture",
+  "reserved-sdk-import",
   "sdk-export-missing",
 ]);
 
@@ -78,6 +79,12 @@ export const issueMetadataByCode = {
     decision: "core-compat-adapter",
     title: "plugin SDK import aliases are missing from target package exports",
   },
+  "reserved-sdk-import": {
+    severity: "P1",
+    owner: "plugin",
+    decision: "plugin-upstream-fix",
+    title: "plugin imports reserved bundled-plugin SDK compatibility subpaths",
+  },
   "missing-compat-record": {
     severity: "P1",
     owner: "core",
@@ -310,6 +317,7 @@ function issueClassFor(code, options) {
       "package-openclaw-entry-missing",
       "package-openclaw-metadata-missing",
       "package-plugin-api-compat-missing",
+      "reserved-sdk-import",
     ].includes(code)
   ) {
     return "upstream-metadata";

package/src/openclaw-target.js

@@ -31,6 +31,7 @@ export async function readOpenClawTargetSurface(options = {}) {
   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 pluginSdkEntrypointsPath = path.join(resolvedPath, "src/plugin-sdk/entrypoints.ts");
   const packagePath = path.join(resolvedPath, "package.json");
 
   const registrySource = await readFile(registryPath, "utf8");
@@ -48,6 +49,18 @@ export async function readOpenClawTargetSurface(options = {}) {
   const sdkExports = existsSync(packagePath)
     ? parsePluginSdkExports(JSON.parse(await readFile(packagePath, "utf8")))
     : [];
+  const pluginSdkEntrypointsSource = existsSync(pluginSdkEntrypointsPath)
+    ? await readFile(pluginSdkEntrypointsPath, "utf8")
+    : "";
+  const reservedSdkExports = pluginSdkEntrypointsSource
+    ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "reservedBundledPluginSdkEntrypoints")
+    : [];
+  const supportedFacadeSdkExports = pluginSdkEntrypointsSource
+    ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "supportedBundledFacadeSdkEntrypoints")
+    : [];
+  const publicPluginOwnedSdkExports = pluginSdkEntrypointsSource
+    ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "publicPluginOwnedSdkEntrypoints")
+    : [];
 
   return {
     configuredPath: requestedPath,
@@ -69,6 +82,13 @@ export async function readOpenClawTargetSurface(options = {}) {
     packagePath: existsSync(packagePath) ? relativePath(rootDir, packagePath) : null,
     sdkExportCount: sdkExports.length,
     sdkExports,
+    pluginSdkEntrypointsPath: existsSync(pluginSdkEntrypointsPath)
+      ? relativePath(rootDir, pluginSdkEntrypointsPath)
+      : null,
+    reservedSdkExportCount: reservedSdkExports.length,
+    reservedSdkExports,
+    supportedFacadeSdkExports,
+    publicPluginOwnedSdkExports,
     manifestTypesPath: existsSync(manifestTypesPath) ? relativePath(rootDir, manifestTypesPath) : null,
     manifestFieldCount: manifestFields.length,
     manifestFields,
@@ -149,11 +169,18 @@ function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status
     apiRegistrars: [],
     capturedRegistrars: [],
     sdkExports: [],
+    reservedSdkExports: [],
+    supportedFacadeSdkExports: [],
+    publicPluginOwnedSdkExports: [],
     manifestFields: [],
     manifestContractFields: [],
   };
 }
 
+export function parsePluginSdkEntrypointSpecifiers(source, exportName) {
+  return parseExportedStringArray(source, exportName).map((entrypoint) => `openclaw/plugin-sdk/${entrypoint}`).sort();
+}
+
 function parseCapturedRegistrars(source) {
   return unique([...source.matchAll(/^\s*(register[A-Za-z0-9]+)\s*\(/gm)].map((match) => match[1])).sort();
 }

package/src/report.js

@@ -160,6 +160,7 @@ export async function buildCompatibilityReport(options = {}) {
       warningCount: warnings.length,
       suggestionCount: suggestions.length,
       decisionCount: decisions.length,
+      logCount: logs.length,
       issueCount: issues.length,
       p0IssueCount: issues.filter((issue) => issue.severity === "P0").length,
       p1IssueCount: issues.filter((issue) => issue.severity === "P1").length,

package/src/sdk-mock.js

@@ -718,6 +718,37 @@ function mockSdkSource() {
   return typeof entry === "function" ? { register: entry } : entry;
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseWithSchema(schema, value) {
+  return schema && typeof schema.parse === "function" ? schema.parse(value) : value;
+}
+
+function createConfigSchema(schema = {}) {
+  if (schema && typeof schema.parse === "function") {
+    return schema;
+  }
+  const shape = isPlainObject(schema?.shape) ? schema.shape : isPlainObject(schema?.properties) ? schema.properties : schema;
+  return {
+    ...schema,
+    parse(value = {}) {
+      if (!isPlainObject(shape)) {
+        return isPlainObject(value) ? value : {};
+      }
+      const source = isPlainObject(value) ? value : {};
+      const output = { ...source };
+      for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+          output[key] = parseWithSchema(fieldSchema, source[key]);
+        }
+      }
+      return output;
+    },
+  };
+}
+
 export function definePluginEntry(entry) {
   return normalizeEntry(entry);
 }
@@ -759,13 +790,13 @@ export function defineSingleProviderPluginEntry(options) {
 }
 
 export function buildPluginConfigSchema(schema = {}) {
-  return schema;
+  return createConfigSchema(schema);
 }
 
-export const emptyPluginConfigSchema = { type: "object", properties: {}, additionalProperties: false };
+export const emptyPluginConfigSchema = createConfigSchema({ type: "object", properties: {}, additionalProperties: false });
 
 export function buildChannelConfigSchema(schema = {}) {
-  return schema;
+  return createConfigSchema(schema);
 }
 
 export const emptyChannelConfigSchema = emptyPluginConfigSchema;
@@ -951,14 +982,28 @@ export function createAuthRateLimiter() {
 }
 
 export function createProviderApiKeyAuthMethod(options = {}) {
-  return { type: "apiKey", ...options };
+  return {
+    id: options.id ?? "apiKey",
+    type: "apiKey",
+    ...options,
+    async resolve(ctx = {}) {
+      return ctx.apiKey ?? ctx.key ?? ctx.token ?? null;
+    },
+  };
 }
 
 export function buildSingleProviderApiKeyCatalog(options = {}) {
+  const auth = options.auth ?? createProviderApiKeyAuthMethod(options.authOptions);
   return {
+    auth,
     order: "simple",
     async run(ctx) {
-      return { provider: await options.buildProvider?.(ctx) };
+      const provider = (await options.buildProvider?.(ctx)) ?? options.provider ?? { id: options.id ?? "provider", auth };
+      return {
+        provider,
+        providers: [provider],
+        models: (await options.buildModels?.(ctx)) ?? options.models ?? [],
+      };
     },
   };
 }

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;
+}