@openclaw/plugin-inspector 0.3.18 → 0.3.20

package/src/openclaw-target.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 
 export const defaultOpenClawCheckoutPaths = ["./openclaw", "../openclaw"];
@@ -26,11 +26,16 @@ export async function readOpenClawTargetSurface(options = {}) {
     });
   }
 
+  if (match.kind === "package") {
+    return readPackedOpenClawTargetSurface({ rootDir, requestedPaths, ...match });
+  }
+
   const { requestedPath, resolvedPath, registryPath } = 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 manifestTypesPath = path.join(resolvedPath, "src/plugins/manifest.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 packagePath = path.join(resolvedPath, "package.json");
 
@@ -40,9 +45,21 @@ export async function readOpenClawTargetSurface(options = {}) {
   const hookNames = hookTypesSource ? parseConstStringArray(hookTypesSource, "PLUGIN_HOOK_NAMES") : [];
   const apiBuilderSource = existsSync(apiBuilderPath) ? await readFile(apiBuilderPath, "utf8") : "";
   const apiRegistrars = apiBuilderSource ? parseApiRegistrars(apiBuilderSource) : [];
-  const manifestTypesSource = existsSync(manifestTypesPath) ? await readFile(manifestTypesPath, "utf8") : "";
-  const manifestFields = manifestTypesSource ? parseTypeFields(manifestTypesSource, "PluginManifest") : [];
-  const manifestContractFields = manifestTypesSource ? parseTypeFields(manifestTypesSource, "PluginManifestContracts") : [];
+  const currentManifestTypesSource = existsSync(currentManifestTypesPath)
+    ? await readFile(currentManifestTypesPath, "utf8")
+    : "";
+  const legacyManifestTypesSource = existsSync(legacyManifestTypesPath)
+    ? await readFile(legacyManifestTypesPath, "utf8")
+    : "";
+  const currentManifestFields = parseTypeFields(currentManifestTypesSource, "PluginManifest");
+  const legacyManifestFields = parseTypeFields(legacyManifestTypesSource, "PluginManifest");
+  const currentManifestContractFields = parseTypeFields(currentManifestTypesSource, "PluginManifestContracts");
+  const legacyManifestContractFields = parseTypeFields(legacyManifestTypesSource, "PluginManifestContracts");
+  const useCurrentManifestTypes = currentManifestFields.length > 0;
+  const manifestTypesPath = useCurrentManifestTypes ? currentManifestTypesPath : legacyManifestTypesPath;
+  const manifestFields = useCurrentManifestTypes ? currentManifestFields : legacyManifestFields;
+  const manifestContractFields =
+    currentManifestContractFields.length > 0 ? currentManifestContractFields : legacyManifestContractFields;
   const capturedRegistrars = existsSync(capturedRegistrationPath)
     ? parseCapturedRegistrars(await readFile(capturedRegistrationPath, "utf8"))
     : [];
@@ -238,12 +255,191 @@ function findTargetCheckout(rootDir, requestedPaths) {
     const resolvedPath = path.resolve(rootDir, requestedPath);
     const registryPath = path.join(resolvedPath, "src/plugins/compat/registry.ts");
     if (existsSync(registryPath)) {
-      return { requestedPath, resolvedPath, registryPath };
+      return { kind: "checkout", requestedPath, resolvedPath, registryPath };
+    }
+    if (existsSync(path.join(resolvedPath, "package.json")) && existsSync(path.join(resolvedPath, "dist"))) {
+      return { kind: "package", requestedPath, resolvedPath };
+    }
+  }
+  return null;
+}
+
+async function readPackedOpenClawTargetSurface({ rootDir, requestedPaths, requestedPath, resolvedPath }) {
+  const packagePath = path.join(resolvedPath, "package.json");
+  const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+  if (packageJson.name !== "openclaw") {
+    return emptyTargetSurface({ configuredPath: requestedPath, searchedPaths: requestedPaths, status: "missing" });
+  }
+
+  const distPath = path.join(resolvedPath, "dist");
+  const declarationFiles = await listDeclarationFiles(distPath);
+  const declarations = [];
+  for (const filePath of declarationFiles) {
+    declarations.push({ filePath, source: await readFile(filePath, "utf8") });
+  }
+  const apiDeclaration = declarations
+    .map((declaration) => ({
+      ...declaration,
+      values: parseObjectTypeFields(declaration.source, "OpenClawPluginApi", (value) => value.startsWith("register")),
+    }))
+    .sort((left, right) => right.values.length - left.values.length)[0];
+  const hookDeclaration = declarations.find((declaration) => declaration.source.includes("type PluginHookName ="));
+  const manifestDeclaration = declarations.find((declaration) => declaration.source.includes("type PluginManifestRecord ="));
+  const manifestContractDeclaration = declarations.find((declaration) => declaration.source.includes("type PluginManifestContracts ="));
+  const apiRegistrars = apiDeclaration?.values ?? [];
+  const hookNames = hookDeclaration ? parseStringUnion(hookDeclaration.source, "PluginHookName") : [];
+  const manifestFields = manifestDeclaration
+    ? parseObjectTypeFields(manifestDeclaration.source, "PluginManifestRecord")
+    : [];
+  const manifestContractFields = manifestContractDeclaration
+    ? parseObjectTypeFields(manifestContractDeclaration.source, "PluginManifestContracts")
+    : [];
+  const sdkExports = parsePluginSdkExports(packageJson);
+
+  return {
+    configuredPath: requestedPath,
+    searchedPaths: requestedPaths,
+    status: "ok",
+    version: packageJson.version ?? null,
+    compatRegistryPath: null,
+    compatRecordCount: 0,
+    compatRecords: [],
+    compatRecordStatuses: {},
+    hookTypesPath: hookDeclaration ? relativePath(rootDir, hookDeclaration.filePath) : null,
+    hookNameCount: hookNames.length,
+    hookNames,
+    apiBuilderPath: apiDeclaration ? relativePath(rootDir, apiDeclaration.filePath) : null,
+    apiRegistrarCount: apiRegistrars.length,
+    apiRegistrars,
+    capturedRegistrationPath: apiDeclaration ? relativePath(rootDir, apiDeclaration.filePath) : null,
+    capturedRegistrarCount: apiRegistrars.length,
+    capturedRegistrars: apiRegistrars,
+    packagePath: relativePath(rootDir, packagePath),
+    sdkExportCount: sdkExports.length,
+    sdkExports,
+    pluginSdkEntrypointsPath: null,
+    reservedSdkExportCount: 0,
+    reservedSdkExports: [],
+    supportedFacadeSdkExports: [],
+    publicPluginOwnedSdkExports: [],
+    manifestTypesPath: manifestDeclaration ? relativePath(rootDir, manifestDeclaration.filePath) : null,
+    manifestFieldCount: manifestFields.length,
+    manifestFields,
+    manifestContractFieldCount: manifestContractFields.length,
+    manifestContractFields,
+  };
+}
+
+async function listDeclarationFiles(rootDir) {
+  const files = [];
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listDeclarationFiles(entryPath)));
+    } else if (entry.isFile() && entry.name.endsWith(".d.ts")) {
+      files.push(entryPath);
+    }
+  }
+  return files.sort();
+}
+
+function parseObjectTypeFields(source, typeName, filter = () => true) {
+  const body = readObjectTypeBody(source, typeName);
+  if (!body) return [];
+  return unique(parseTopLevelTypeProperties(body).filter(filter)).sort();
+}
+
+function parseTopLevelTypeProperties(body) {
+  const properties = [];
+  let braceDepth = 0;
+  let bracketDepth = 0;
+  let parenDepth = 0;
+  let propertyStart = true;
+
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index];
+    const next = body[index + 1];
+    if (char === "/" && next === "*") {
+      index = body.indexOf("*/", index + 2);
+      if (index === -1) break;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      const newline = body.indexOf("\n", index + 2);
+      if (newline === -1) break;
+      index = newline;
+      continue;
     }
+    if (char === '"' || char === "'" || char === "`") {
+      index = skipQuotedTypeText(body, index);
+      continue;
+    }
+    if (char === "{") braceDepth += 1;
+    else if (char === "}") braceDepth -= 1;
+    else if (char === "[") bracketDepth += 1;
+    else if (char === "]") bracketDepth -= 1;
+    else if (char === "(") parenDepth += 1;
+    else if (char === ")") parenDepth -= 1;
+
+    if (braceDepth !== 0 || bracketDepth !== 0 || parenDepth !== 0) continue;
+    if (char === ";" || char === ",") {
+      propertyStart = true;
+      continue;
+    }
+    if (/\s/.test(char)) continue;
+    if (!propertyStart || !/[A-Za-z_$]/.test(char)) {
+      propertyStart = false;
+      continue;
+    }
+
+    const match = body.slice(index).match(/^([A-Za-z_$][A-Za-z0-9_$]*)/);
+    if (!match) {
+      propertyStart = false;
+      continue;
+    }
+    const name = match[1];
+    index += name.length - 1;
+    if (name === "readonly") continue;
+    let cursor = index + 1;
+    while (/\s/.test(body[cursor] ?? "")) cursor += 1;
+    if (body[cursor] === "?") cursor += 1;
+    while (/\s/.test(body[cursor] ?? "")) cursor += 1;
+    if (body[cursor] === ":") properties.push(name);
+    propertyStart = false;
+  }
+  return properties;
+}
+
+function skipQuotedTypeText(source, quoteIndex) {
+  const quote = source[quoteIndex];
+  for (let index = quoteIndex + 1; index < source.length; index += 1) {
+    if (source[index] === "\\") index += 1;
+    else if (source[index] === quote) return index;
+  }
+  return source.length - 1;
+}
+
+function readObjectTypeBody(source, typeName) {
+  const marker = new RegExp(`(?:export\\s+)?type\\s+${typeName}(?:\\$\\d+)?\\s*=\\s*\\{`, "g");
+  const match = marker.exec(source);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  let depth = 1;
+  for (let index = start; index < source.length; index += 1) {
+    if (source[index] === "{") depth += 1;
+    if (source[index] === "}") depth -= 1;
+    if (depth === 0) return source.slice(start, index);
   }
   return null;
 }
 
+function parseStringUnion(source, typeName) {
+  const match = source.match(new RegExp(`type\\s+${typeName}\\s*=\\s*([^;]+);`));
+  return match ? unique([...match[1].matchAll(/["']([^"']+)["']/g)].map((item) => item[1])).sort() : [];
+}
+
 function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status }) {
   return {
     configuredPath,

package/src/openclaw-version.js

@@ -0,0 +1,246 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import semver from "semver";
+import { x as extractTar } from "tar";
+import { readOpenClawTargetSurface } from "./openclaw-target.js";
+
+const defaultRegistryUrl = "https://registry.npmjs.org";
+const supportedTags = new Set(["latest", "beta"]);
+const downloadUrls = new WeakMap();
+
+export async function resolveOpenClawTargetVersion(requestedVersion, options = {}) {
+  const requested = requestedVersion ?? "latest";
+  if (typeof requested !== "string" || requested.trim().length === 0) {
+    throw new Error("OpenClaw target version must be latest, beta, or an exact version");
+  }
+
+  const registryUrl = normalizeRegistryUrl(
+    options.registryUrl ?? process.env.PLUGIN_INSPECTOR_NPM_REGISTRY ?? defaultRegistryUrl,
+  );
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  let version = requested;
+  let distTag = null;
+
+  if (supportedTags.has(requested)) {
+    const metadata = await fetchJson(`${registryUrl}/openclaw`, fetchImpl);
+    version = metadata["dist-tags"]?.[requested];
+    if (typeof version !== "string" || version.length === 0) {
+      throw new Error(`OpenClaw npm dist-tag ${requested} did not resolve to an exact version`);
+    }
+    if (!isExactOpenClawVersion(version)) {
+      throw new Error(`OpenClaw npm dist-tag ${requested} did not resolve to a valid exact version`);
+    }
+    distTag = requested;
+  } else if (!isExactOpenClawVersion(requested)) {
+    throw new Error("--openclaw-version must be latest, beta, or an exact OpenClaw version");
+  }
+
+  const versionMetadata = await fetchJson(`${registryUrl}/openclaw/${encodeURIComponent(version)}`, fetchImpl);
+  if (versionMetadata.version !== version || typeof versionMetadata.dist?.tarball !== "string") {
+    throw new Error(`OpenClaw npm metadata for ${version} is incomplete`);
+  }
+  if (!hasVerifiableIntegrity(versionMetadata.dist)) {
+    throw new Error(`OpenClaw npm metadata for ${version} has no verifiable integrity metadata`);
+  }
+
+  const resolvedTarget = {
+    requestedVersion: requested,
+    version,
+    eligibilityVersion: openClawEligibilityVersion(version),
+    source: {
+      type: "npm",
+      package: "openclaw",
+      registry: sanitizeUrlForReport(registryUrl),
+      distTag,
+      tarball: sanitizeUrlForReport(versionMetadata.dist.tarball),
+      integrity: versionMetadata.dist.integrity ?? null,
+      shasum: versionMetadata.dist.shasum ?? null,
+      repository: sanitizeRepositoryForReport(versionMetadata.repository),
+    },
+  };
+  downloadUrls.set(resolvedTarget, versionMetadata.dist.tarball);
+  return resolvedTarget;
+}
+
+export async function prepareOpenClawTarget(resolvedTarget, options = {}) {
+  if (!resolvedTarget?.version || !resolvedTarget?.source?.integrity && !resolvedTarget?.source?.shasum) {
+    throw new Error("prepareOpenClawTarget requires a resolved npm target");
+  }
+  if (!downloadUrls.has(resolvedTarget)) {
+    throw new Error("prepareOpenClawTarget requires the target object directly returned by resolveOpenClawTargetVersion");
+  }
+
+  const cacheDir = path.resolve(
+    options.cacheDir ??
+      process.env.PLUGIN_INSPECTOR_CACHE_DIR ??
+      path.join(process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache"), "plugin-inspector"),
+  );
+  const cacheKey = cacheKeyFor(resolvedTarget);
+  const targetDir = path.join(cacheDir, "openclaw", cacheKey);
+  const packageDir = path.join(targetDir, "package");
+  let cacheHit = await isPreparedPackage(packageDir, resolvedTarget.version);
+
+  if (!cacheHit) {
+    await preparePackageArchive(resolvedTarget, { ...options, cacheDir, targetDir });
+    cacheHit = false;
+  }
+
+  const surface = await readOpenClawTargetSurface({ rootDir: packageDir, configuredPath: "." });
+  if (surface.status !== "ok") {
+    throw new Error(`prepared OpenClaw ${resolvedTarget.version} package has no readable public plugin surface`);
+  }
+
+  return {
+    ...surface,
+    configuredPath: `npm:openclaw@${resolvedTarget.version}`,
+    searchedPaths: [`npm:openclaw@${resolvedTarget.version}`],
+    requestedVersion: resolvedTarget.requestedVersion,
+    version: resolvedTarget.version,
+    eligibilityVersion: resolvedTarget.eligibilityVersion,
+    source: resolvedTarget.source,
+    cache: { hit: cacheHit, key: cacheKey },
+  };
+}
+
+export function openClawEligibilityVersion(version) {
+  const parsed = semver.parse(version);
+  return parsed ? `${parsed.major}.${parsed.minor}.${parsed.patch}` : version;
+}
+
+export function satisfiesOpenClawVersionRange(version, range) {
+  return Boolean(semver.valid(version) && semver.validRange(range) && semver.satisfies(version, range));
+}
+
+export function satisfiesOpenClawCompatibilityRange({ targetVersion, eligibilityVersion, range }) {
+  try {
+    const target = semver.parse(targetVersion);
+    if (!target) return false;
+    return new semver.Range(range).set.some((comparators) => {
+      const branch = comparators.map((comparator) => comparator.value).filter(Boolean).join(" ") || "*";
+      if (semver.satisfies(targetVersion, branch)) return true;
+      const constrainsTargetPrerelease = comparators.some(
+        (comparator) =>
+          (comparator.semver?.prerelease?.length ?? 0) > 0 &&
+          comparator.semver.major === target.major &&
+          comparator.semver.minor === target.minor &&
+          comparator.semver.patch === target.patch,
+      );
+      return !constrainsTargetPrerelease && semver.satisfies(eligibilityVersion, branch);
+    });
+  } catch {
+    return false;
+  }
+}
+
+async function preparePackageArchive(resolvedTarget, options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(downloadUrlFor(resolvedTarget));
+  if (!response.ok) {
+    throw new Error(`failed to download OpenClaw ${resolvedTarget.version}: HTTP ${response.status}`);
+  }
+  const archive = Buffer.from(await response.arrayBuffer());
+  verifyArchive(archive, resolvedTarget.source);
+
+  await mkdir(path.dirname(options.targetDir), { recursive: true });
+  const temporaryDir = await mkdtemp(path.join(path.dirname(options.targetDir), `.${path.basename(options.targetDir)}-`));
+  try {
+    const archivePath = path.join(temporaryDir, "openclaw.tgz");
+    await writeFile(archivePath, archive);
+    await extractTar({ cwd: temporaryDir, file: archivePath, strict: true });
+    const packageDir = path.join(temporaryDir, "package");
+    if (!(await isPreparedPackage(packageDir, resolvedTarget.version))) {
+      throw new Error(`downloaded OpenClaw ${resolvedTarget.version} archive has unexpected package metadata`);
+    }
+    await rm(archivePath, { force: true });
+    try {
+      await rename(temporaryDir, options.targetDir);
+    } catch (error) {
+      if (error?.code !== "EEXIST" && error?.code !== "ENOTEMPTY") throw error;
+    }
+  } finally {
+    await rm(temporaryDir, { recursive: true, force: true });
+  }
+}
+
+async function isPreparedPackage(packageDir, version) {
+  if (!existsSync(path.join(packageDir, "package.json"))) return false;
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(packageDir, "package.json"), "utf8"));
+    return packageJson.name === "openclaw" && packageJson.version === version;
+  } catch {
+    return false;
+  }
+}
+
+function verifyArchive(archive, source) {
+  if (typeof source.integrity === "string" && source.integrity.startsWith("sha512-")) {
+    const actual = createHash("sha512").update(archive).digest("base64");
+    if (actual !== source.integrity.slice("sha512-".length)) throw new Error("OpenClaw npm archive failed integrity verification");
+    return;
+  }
+  if (typeof source.shasum === "string" && /^[a-f0-9]{40}$/i.test(source.shasum)) {
+    const actual = createHash("sha1").update(archive).digest("hex");
+    if (actual !== source.shasum.toLowerCase()) throw new Error("OpenClaw npm archive failed shasum verification");
+    return;
+  }
+  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();
+}
+
+function cacheKeyFor(target) {
+  const identity = target.source.integrity ?? target.source.shasum ?? target.source.tarball;
+  const digest = createHash("sha256").update(String(identity)).digest("hex").slice(0, 12);
+  return `${target.version}-${digest}`;
+}
+
+function downloadUrlFor(target) {
+  return downloadUrls.get(target) ?? null;
+}
+
+function hasVerifiableIntegrity(dist) {
+  return (
+    (typeof dist.integrity === "string" && /^sha512-[A-Za-z0-9+/]+=*$/.test(dist.integrity)) ||
+    (typeof dist.shasum === "string" && /^[a-f0-9]{40}$/i.test(dist.shasum))
+  );
+}
+
+function isExactOpenClawVersion(value) {
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value) && semver.valid(value) === value;
+}
+
+function normalizeRegistryUrl(value) {
+  const url = String(value);
+  let end = url.length;
+  while (end > 0 && url.charCodeAt(end - 1) === 47) end -= 1;
+  return url.slice(0, end);
+}
+
+function sanitizeUrlForReport(value) {
+  try {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeRepositoryForReport(repository) {
+  if (typeof repository === "string") return sanitizeUrlForReport(repository);
+  if (!repository || typeof repository !== "object") return null;
+  return {
+    ...repository,
+    url: typeof repository.url === "string" ? sanitizeUrlForReport(repository.url) : null,
+  };
+}

package/src/report.js

@@ -110,6 +110,7 @@ export async function buildCompatibilityReport(options = {}) {
       fixtureReport,
       targetOpenClaw,
     });
+    breakages.push(...fixtureClassification.breakages);
     warnings.push(...fixtureClassification.warnings);
     suggestions.push(...fixtureClassification.suggestions);
     logs.push(...fixtureClassification.logs);