@openclaw/plugin-inspector 0.3.24 → 0.3.26

package/src/openclaw-target.js

@@ -30,17 +30,36 @@ export async function readOpenClawTargetSurface(options = {}) {
     return readPackedOpenClawTargetSurface({ rootDir, requestedPaths, ...match });
   }
 
-  const { requestedPath, resolvedPath, registryPath } = match;
+  const { requestedPath, resolvedPath, registryPath: registryEntryPath } = 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 currentManifestTypesPath = path.join(resolvedPath, "src/plugins/manifest-types.ts");
   const legacyManifestTypesPath = path.join(resolvedPath, "src/plugins/manifest.ts");
   const pluginSdkEntrypointsPath = path.join(resolvedPath, "src/plugin-sdk/entrypoints.ts");
+  const privateLocalSdkSubpathsPath = path.join(
+    resolvedPath,
+    "scripts/lib/plugin-sdk-private-local-only-subpaths.json",
+  );
   const packagePath = path.join(resolvedPath, "package.json");
 
-  const registrySource = await readFile(registryPath, "utf8");
+  const registryEntrySource = await readFile(registryEntryPath, "utf8");
+  const registryPath = importsCompatRecords(registryEntrySource)
+    ? path.join(path.dirname(registryEntryPath), "registry-records.ts")
+    : registryEntryPath;
+  const registrySource = registryPath === registryEntryPath
+    ? registryEntrySource
+    : await readFile(registryPath, "utf8");
   const compatRecordEntries = parseCompatRecordEntries(registrySource);
+  const compatRecordTests = Object.fromEntries(
+    compatRecordEntries.map((record) => [record.code, record.tests]),
+  );
+  const compatRecordMissingTests = Object.fromEntries(
+    compatRecordEntries.map((record) => [
+      record.code,
+      record.tests.filter((testPath) => !existsSync(path.join(resolvedPath, testPath))),
+    ]),
+  );
   const hookTypesSource = existsSync(hookTypesPath) ? await readFile(hookTypesPath, "utf8") : "";
   const hookNames = hookTypesSource ? parseConstStringArray(hookTypesSource, "PLUGIN_HOOK_NAMES") : [];
   const apiBuilderSource = existsSync(apiBuilderPath) ? await readFile(apiBuilderPath, "utf8") : "";
@@ -66,12 +85,21 @@ export async function readOpenClawTargetSurface(options = {}) {
   const sdkExports = existsSync(packagePath)
     ? parsePluginSdkExports(JSON.parse(await readFile(packagePath, "utf8")))
     : [];
+  const privateLocalSdkExports = existsSync(privateLocalSdkSubpathsPath)
+    ? parsePluginSdkSubpathSpecifiers(
+        JSON.parse(await readFile(privateLocalSdkSubpathsPath, "utf8")),
+      )
+    : [];
   const pluginSdkEntrypointsSource = existsSync(pluginSdkEntrypointsPath)
     ? await readFile(pluginSdkEntrypointsPath, "utf8")
     : "";
   const reservedSdkExports = pluginSdkEntrypointsSource
     ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "reservedBundledPluginSdkEntrypoints")
     : [];
+  const bundledPluginIds = await readBundledPluginIds(resolvedPath);
+  const reservedSdkExportOwners = Object.fromEntries(
+    reservedSdkExports.map((specifier) => [specifier, resolveBundledSdkOwner(specifier, bundledPluginIds)]),
+  );
   const supportedFacadeSdkExports = pluginSdkEntrypointsSource
     ? parsePluginSdkEntrypointSpecifiers(pluginSdkEntrypointsSource, "supportedBundledFacadeSdkEntrypoints")
     : [];
@@ -81,12 +109,15 @@ export async function readOpenClawTargetSurface(options = {}) {
 
   return {
     configuredPath: requestedPath,
+    checkoutPath: relativePath(rootDir, resolvedPath) || ".",
     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])),
+    compatRecordTests,
+    compatRecordMissingTests,
     hookTypesPath: existsSync(hookTypesPath) ? relativePath(rootDir, hookTypesPath) : null,
     hookNameCount: hookNames.length,
     hookNames,
@@ -99,11 +130,14 @@ export async function readOpenClawTargetSurface(options = {}) {
     packagePath: existsSync(packagePath) ? relativePath(rootDir, packagePath) : null,
     sdkExportCount: sdkExports.length,
     sdkExports,
+    privateLocalSdkExportCount: privateLocalSdkExports.length,
+    privateLocalSdkExports,
     pluginSdkEntrypointsPath: existsSync(pluginSdkEntrypointsPath)
       ? relativePath(rootDir, pluginSdkEntrypointsPath)
       : null,
     reservedSdkExportCount: reservedSdkExports.length,
     reservedSdkExports,
+    reservedSdkExportOwners,
     supportedFacadeSdkExports,
     publicPluginOwnedSdkExports,
     manifestTypesPath: existsSync(manifestTypesPath) ? relativePath(rootDir, manifestTypesPath) : null,
@@ -121,6 +155,23 @@ export function openClawTargetPathCandidates(manifest, configuredPath) {
   return unique([manifest?.openclaw?.defaultCheckoutPath, ...defaultOpenClawCheckoutPaths].filter(Boolean));
 }
 
+function importsCompatRecords(source) {
+  // Keep quoted text atomic and discard comments before recognizing the fixed delegation.
+  const tokens = (source.match(/\/\/[^\r\n]*|\/\*[\s\S]*?(?:\*\/|$)|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`|[$A-Z_a-z][$\w]*|[^\s]/g) ?? [])
+    .filter((token) => !token.startsWith("//") && !token.startsWith("/*"));
+  for (let index = 0; index < tokens.length; index += 1) {
+    if (tokens[index] !== "import" || tokens[index + 1] !== "{") continue;
+    const end = tokens.indexOf("}", index + 2);
+    if (end === -1 || tokens[end + 1] !== "from") continue;
+    if (!['"./registry-records.js"', "'./registry-records.js'"].includes(tokens[end + 2])) continue;
+    const bindings = tokens.slice(index + 2, end).join(" ").split(",");
+    if (bindings.some((binding) => /^PLUGIN_COMPAT_RECORDS(?:\s+as\s+[$A-Z_a-z][$\w]*)?$/.test(binding.trim()))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export function parseCompatRecordEntries(source) {
   const entries = [];
   let cursor = 0;
@@ -132,8 +183,14 @@ export function parseCompatRecordEntries(source) {
 
     const statusProperty = readStringProperty(source, "status", codeProperty.end);
     if (statusProperty) {
-      entries.push({ code: codeProperty.value, status: statusProperty.value });
-      cursor = statusProperty.end;
+      const nextCodeProperty = readStringProperty(source, "code", statusProperty.end);
+      const recordEnd = nextCodeProperty?.propertyIndex ?? source.length;
+      entries.push({
+        code: codeProperty.value,
+        status: statusProperty.value,
+        tests: readStringArrayProperty(source, "tests", statusProperty.end, recordEnd),
+      });
+      cursor = recordEnd;
     } else {
       cursor = codeProperty.end;
     }
@@ -157,7 +214,21 @@ function readStringProperty(source, property, fromIndex) {
   if (!isQuote(source[quoteIndex])) {
     return null;
   }
-  return readQuotedValue(source, quoteIndex);
+  const value = readQuotedValue(source, quoteIndex);
+  return value ? { ...value, propertyIndex } : null;
+}
+
+function readStringArrayProperty(source, property, fromIndex, toIndex) {
+  const propertyIndex = findProperty(source, property, fromIndex);
+  if (propertyIndex === -1 || propertyIndex >= toIndex) return [];
+  const colonIndex = source.indexOf(":", propertyIndex + property.length);
+  const openIndex = source.indexOf("[", colonIndex + 1);
+  if (colonIndex === -1 || openIndex === -1 || openIndex >= toIndex) return [];
+  const closeIndex = source.indexOf("]", openIndex + 1);
+  if (closeIndex === -1 || closeIndex >= toIndex) return [];
+  return unique(
+    [...source.slice(openIndex + 1, closeIndex).matchAll(/["']([^"']+)["']/g)].map((match) => match[1]),
+  ).sort();
 }
 
 function findProperty(source, property, fromIndex) {
@@ -298,6 +369,7 @@ async function readPackedOpenClawTargetSurface({ rootDir, requestedPaths, reques
 
   return {
     configuredPath: requestedPath,
+    checkoutPath: relativePath(rootDir, resolvedPath) || ".",
     searchedPaths: requestedPaths,
     status: "ok",
     version: packageJson.version ?? null,
@@ -305,6 +377,8 @@ async function readPackedOpenClawTargetSurface({ rootDir, requestedPaths, reques
     compatRecordCount: 0,
     compatRecords: [],
     compatRecordStatuses: {},
+    compatRecordTests: {},
+    compatRecordMissingTests: {},
     hookTypesPath: hookDeclaration ? relativePath(rootDir, hookDeclaration.filePath) : null,
     hookNameCount: hookNames.length,
     hookNames,
@@ -317,9 +391,12 @@ async function readPackedOpenClawTargetSurface({ rootDir, requestedPaths, reques
     packagePath: relativePath(rootDir, packagePath),
     sdkExportCount: sdkExports.length,
     sdkExports,
+    privateLocalSdkExportCount: 0,
+    privateLocalSdkExports: [],
     pluginSdkEntrypointsPath: null,
     reservedSdkExportCount: 0,
     reservedSdkExports: [],
+    reservedSdkExportOwners: {},
     supportedFacadeSdkExports: [],
     publicPluginOwnedSdkExports: [],
     manifestTypesPath: manifestDeclaration ? relativePath(rootDir, manifestDeclaration.filePath) : null,
@@ -443,15 +520,20 @@ function parseStringUnion(source, typeName) {
 function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status }) {
   return {
     configuredPath,
+    checkoutPath: null,
     searchedPaths,
     status,
     compatRecords: [],
     compatRecordStatuses: {},
+    compatRecordTests: {},
+    compatRecordMissingTests: {},
     hookNames: [],
     apiRegistrars: [],
     capturedRegistrars: [],
     sdkExports: [],
+    privateLocalSdkExports: [],
     reservedSdkExports: [],
+    reservedSdkExportOwners: {},
     supportedFacadeSdkExports: [],
     publicPluginOwnedSdkExports: [],
     manifestFields: [],
@@ -459,10 +541,33 @@ function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status
   };
 }
 
+async function readBundledPluginIds(openClawRoot) {
+  const extensionsRoot = path.join(openClawRoot, "extensions");
+  if (!existsSync(extensionsRoot)) return [];
+  return (await readdir(extensionsRoot, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((left, right) => right.length - left.length || left.localeCompare(right));
+}
+
+function resolveBundledSdkOwner(specifier, pluginIds) {
+  const entrypoint = specifier.slice("openclaw/plugin-sdk/".length);
+  return pluginIds.find((pluginId) => entrypoint === pluginId || entrypoint.startsWith(`${pluginId}-`)) ?? null;
+}
+
 export function parsePluginSdkEntrypointSpecifiers(source, exportName) {
   return parseExportedStringArray(source, exportName).map((entrypoint) => `openclaw/plugin-sdk/${entrypoint}`).sort();
 }
 
+function parsePluginSdkSubpathSpecifiers(value) {
+  if (!Array.isArray(value)) return [];
+  return unique(
+    value
+      .filter((entrypoint) => typeof entrypoint === "string" && !entrypoint.includes("/"))
+      .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/openclaw-version.js

@@ -8,6 +8,9 @@ import { x as extractTar } from "tar";
 import { readOpenClawTargetSurface } from "./openclaw-target.js";
 
 const defaultRegistryUrl = "https://registry.npmjs.org";
+const defaultFetchTimeoutMs = 30_000;
+const defaultMaxArchiveBytes = 256 * 1024 * 1024;
+const defaultMaxMetadataBytes = 16 * 1024 * 1024;
 const supportedTags = new Set(["latest", "beta"]);
 const downloadUrls = new WeakMap();
 
@@ -25,8 +28,8 @@ export async function resolveOpenClawTargetVersion(requestedVersion, options = {
   let distTag = null;
 
   if (supportedTags.has(requested)) {
-    const metadata = await fetchJson(`${registryUrl}/openclaw`, fetchImpl);
-    version = metadata["dist-tags"]?.[requested];
+    const distTags = await fetchJson(`${registryUrl}/-/package/openclaw/dist-tags`, fetchImpl, options);
+    version = distTags?.[requested];
     if (typeof version !== "string" || version.length === 0) {
       throw new Error(`OpenClaw npm dist-tag ${requested} did not resolve to an exact version`);
     }
@@ -38,7 +41,7 @@ export async function resolveOpenClawTargetVersion(requestedVersion, options = {
     throw new Error("--openclaw-version must be latest, beta, or an exact OpenClaw version");
   }
 
-  const versionMetadata = await fetchJson(`${registryUrl}/openclaw/${encodeURIComponent(version)}`, fetchImpl);
+  const versionMetadata = await fetchJson(`${registryUrl}/openclaw/${encodeURIComponent(version)}`, fetchImpl, options);
   if (versionMetadata.version !== version || typeof versionMetadata.dist?.tarball !== "string") {
     throw new Error(`OpenClaw npm metadata for ${version} is incomplete`);
   }
@@ -137,11 +140,12 @@ export function satisfiesOpenClawCompatibilityRange({ targetVersion, eligibility
 
 async function preparePackageArchive(resolvedTarget, options) {
   const fetchImpl = options.fetch ?? globalThis.fetch;
-  const response = await fetchImpl(downloadUrlFor(resolvedTarget));
+  const response = await fetchWithTimeout(fetchImpl, downloadUrlFor(resolvedTarget), {}, options, "npm archive");
   if (!response.ok) {
+    await cancelBody(response.body);
     throw new Error(`failed to download OpenClaw ${resolvedTarget.version}: HTTP ${response.status}`);
   }
-  const archive = Buffer.from(await response.arrayBuffer());
+  const archive = await readLimitedBody(response, maxArchiveBytes(options), "npm archive");
   verifyArchive(archive, resolvedTarget.source);
 
   await mkdir(path.dirname(options.targetDir), { recursive: true });
@@ -191,10 +195,118 @@ function verifyArchive(archive, source) {
   throw new Error("OpenClaw npm archive has no supported integrity metadata");
 }
 
-async function fetchJson(url, fetchImpl) {
-  const response = await fetchImpl(url, { headers: { accept: "application/json" } });
-  if (!response.ok) throw new Error(`failed to resolve OpenClaw npm metadata: HTTP ${response.status}`);
-  return response.json();
+async function fetchJson(url, fetchImpl, options = {}) {
+  const response = await fetchWithTimeout(
+    fetchImpl,
+    url,
+    { headers: { accept: "application/json" } },
+    options,
+    "npm metadata",
+  );
+  if (!response.ok) {
+    await cancelBody(response.body);
+    throw new Error(`failed to resolve OpenClaw npm metadata: HTTP ${response.status}`);
+  }
+  const body = await readLimitedBody(response, maxMetadataBytes(options), "npm metadata");
+  return JSON.parse(body.toString("utf8"));
+}
+
+async function fetchWithTimeout(fetchImpl, url, init, options, what) {
+  try {
+    return await fetchImpl(url, { ...init, signal: AbortSignal.timeout(fetchTimeoutMs(options)) });
+  } catch (error) {
+    throw mapTargetFetchError(error, what);
+  }
+}
+
+async function readLimitedBody(response, maxBytes, what) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await cancelBody(response.body);
+    throw targetDownloadLimitError(what, maxBytes);
+  }
+
+  let reader;
+  try {
+    if (!response.body || typeof response.body.getReader !== "function") {
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (buffer.length > maxBytes) throw targetDownloadLimitError(what, maxBytes);
+      return buffer;
+    }
+
+    reader = response.body.getReader();
+    const chunks = [];
+    let received = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.byteLength;
+      if (received > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {}
+        throw targetDownloadLimitError(what, maxBytes);
+      }
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+  } catch (error) {
+    throw mapTargetFetchError(error, what);
+  } finally {
+    reader?.releaseLock();
+  }
+}
+
+async function cancelBody(body) {
+  try {
+    await body?.cancel?.();
+  } catch {}
+}
+
+function fetchTimeoutMs(options) {
+  const timeout = positiveInteger(
+    options.fetchTimeoutMs ?? process.env.PLUGIN_INSPECTOR_TARGET_FETCH_TIMEOUT_MS,
+    defaultFetchTimeoutMs,
+  );
+  // Node clamps overflowing timer delays to 1ms instead of honoring the budget.
+  return timeout <= 2_147_483_647 ? timeout : defaultFetchTimeoutMs;
+}
+
+function maxArchiveBytes(options) {
+  return positiveInteger(options.maxArchiveBytes ?? process.env.PLUGIN_INSPECTOR_TARGET_ARCHIVE_MAX_BYTES, defaultMaxArchiveBytes);
+}
+
+function maxMetadataBytes(options) {
+  return positiveInteger(options.maxMetadataBytes ?? process.env.PLUGIN_INSPECTOR_TARGET_METADATA_MAX_BYTES, defaultMaxMetadataBytes);
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function mapTargetFetchError(error, what) {
+  if (error?.failureClass) return error;
+  if (isTimeoutError(error)) {
+    const wrapped = new Error(`OpenClaw ${what} download timed out`);
+    wrapped.failureClass = "target-download-timeout";
+    wrapped.cause = error;
+    return wrapped;
+  }
+  return error;
+}
+
+function isTimeoutError(error) {
+  for (let current = error; current; current = current.cause) {
+    if (current.name === "TimeoutError" || current.name === "AbortError") return true;
+  }
+  return false;
+}
+
+function targetDownloadLimitError(what, maxBytes) {
+  const error = new Error(`OpenClaw ${what} exceeds the ${maxBytes} byte download limit`);
+  error.failureClass = "target-download-too-large";
+  return error;
 }
 
 function cacheKeyFor(target) {