@openclaw/plugin-inspector 0.3.4 → 0.3.6

package/src/fixture-summary.js

@@ -19,9 +19,12 @@ const channelRegistrations = new Set([
   "registerChannel",
 ]);
 const hostLinkedRuntimeDependencies = new Set(["openclaw"]);
+const unsupportedSecurityManifestName = "openclaw.security.json";
+const unavailableSecurityManifestSchema = "https://openclaw.ai/schemas/plugin-security.json";
 
 export async function buildCompatibilityFixtureReport({ fixture, inspection, checkoutPath, sourceRoot, rootDir = process.cwd() }) {
   const pluginManifests = await readPluginManifests({ checkoutPath, sourceRoot, rootDir });
+  const securityManifests = await readSecurityManifests({ checkoutPath, sourceRoot, rootDir });
   const packageSummaries = await readPackageSummaries({ checkoutPath, sourceRoot, rootDir });
   const packageJson = selectPrimaryPackage(packageSummaries);
   const sdkImports = unique((inspection.sdkImports ?? []).map((sdkImport) => sdkImport.specifier));
@@ -41,6 +44,7 @@ export async function buildCompatibilityFixtureReport({ fixture, inspection, che
     manifestFiles: inspection.manifestFiles ?? [],
     sourceFiles: inspection.sourceFiles ?? [],
     pluginManifests,
+    securityManifests,
     package: packageJson,
     packages: packageSummaries,
     sdkImports,
@@ -74,6 +78,46 @@ export async function readPluginManifests({ checkoutPath, sourceRoot, rootDir =
   return manifests;
 }
 
+export async function readSecurityManifests({ checkoutPath, sourceRoot, rootDir = process.cwd() }) {
+  const candidates = unique(
+    [
+      path.join(sourceRoot, unsupportedSecurityManifestName),
+      path.join(checkoutPath, unsupportedSecurityManifestName),
+    ].filter(existsSync),
+  );
+  const manifests = [];
+
+  for (const manifestPath of candidates) {
+    const relativePath = path.relative(rootDir, manifestPath);
+    try {
+      const manifest = await readJsonFile(manifestPath);
+      manifests.push({
+        path: relativePath,
+        schema: typeof manifest.$schema === "string" ? manifest.$schema : null,
+        version: typeof manifest.version === "string" ? manifest.version : null,
+        plugin: typeof manifest.plugin === "string" ? manifest.plugin : null,
+        expectedBehaviorCount: Array.isArray(manifest.expectedBehaviors)
+          ? manifest.expectedBehaviors.length
+          : 0,
+        securityNoteCount: Array.isArray(manifest.securityNotes) ? manifest.securityNotes.length : 0,
+        validJson: true,
+      });
+    } catch {
+      manifests.push({
+        path: relativePath,
+        schema: null,
+        version: null,
+        plugin: null,
+        expectedBehaviorCount: 0,
+        securityNoteCount: 0,
+        validJson: false,
+      });
+    }
+  }
+
+  return manifests;
+}
+
 export async function readPackageSummaries({ checkoutPath, sourceRoot, rootDir = process.cwd(), maxDepth = 3 }) {
   const candidates = unique([
     path.join(sourceRoot, "package.json"),
@@ -108,6 +152,9 @@ export function summarizePackage(packagePath, packageJson, options = {}) {
           typeof packageJson.openclaw.build?.pluginSdkVersion === "string"
             ? packageJson.openclaw.build.pluginSdkVersion
             : null,
+        install: summarizeOpenClawInstall(packageJson.openclaw.install),
+        release: summarizeOpenClawRelease(packageJson.openclaw.release),
+        unsupportedMetadata: unsupportedOpenClawPackageMetadata(packageJson.openclaw),
       }
     : null;
 
@@ -121,6 +168,7 @@ export function summarizePackage(packagePath, packageJson, options = {}) {
     version: packageJson.version ?? null,
     type: packageJson.type ?? null,
     main: typeof packageJson.main === "string" ? packageJson.main : null,
+    npmPack: summarizeNpmPack(packageJson, openclaw),
     dependencies: Object.keys(packageJson.dependencies ?? {}).sort(),
     peerDependencies: Object.keys(packageJson.peerDependencies ?? {}).sort(),
     optionalDependencies: Object.keys(packageJson.optionalDependencies ?? {}).sort(),
@@ -202,6 +250,79 @@ export function classifyPackageContracts({ fixture, inspection, fixtureReport })
     });
   }
 
+  if ((packageSummary.openclaw?.unsupportedMetadata ?? []).length > 0) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "package-openclaw-unsupported-metadata",
+      level: "warning",
+      message: "package declares unsupported OpenClaw metadata",
+      evidence: packageSummary.openclaw.unsupportedMetadata,
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "package-metadata",
+      action: "Remove unsupported OpenClaw metadata; native plugins use openclaw.plugin.json plus supported package openclaw fields.",
+      evidence: packageSummary.openclaw.unsupportedMetadata.join(", "),
+    });
+  }
+
+  const installMetadataIssues = packageInstallMetadataIssues(packageSummary);
+  if (installMetadataIssues.length > 0) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "package-install-metadata-incomplete",
+      level: "warning",
+      message: "package OpenClaw install metadata does not match advertised release targets",
+      evidence: installMetadataIssues,
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "package-metadata",
+      action: "Ask the plugin to align openclaw.install metadata with openclaw.release publishing targets.",
+      evidence: installMetadataIssues.join(", "),
+    });
+  }
+
+  if (packageMinHostVersionDrift(packageSummary)) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "package-min-host-version-drift",
+      level: "warning",
+      message: "package openclaw.install.minHostVersion is not a semver floor for the target OpenClaw build version",
+      evidence: [
+        `minHostVersion:${packageSummary.openclaw.install.minHostVersion}`,
+        `buildOpenClawVersion:${packageSummary.openclaw.buildOpenClawVersion}`,
+      ],
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "package-metadata",
+      action: "Ask the plugin to publish install.minHostVersion as a semver floor for the OpenClaw package surface it targets.",
+      evidence: packageSummary.path,
+    });
+  }
+
+  const npmPackIssues = packageNpmPackIssues(packageSummary, fixtureReport);
+  for (const finding of npmPackIssues) {
+    warnings.push({
+      fixture: fixture.id,
+      code: finding.code,
+      level: "warning",
+      message: finding.message,
+      evidence: finding.evidence,
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "package-artifact",
+      action: "Ask the plugin to make its advertised npm install artifact match the published OpenClaw metadata.",
+      evidence: finding.evidence.join(", "),
+    });
+  }
+
   if (packageSummary.openclaw && packageSummary.openclaw.entrypoints.length === 0) {
     warnings.push({
       fixture: fixture.id,
@@ -351,6 +472,7 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   suggestions.push(...packageContracts.suggestions);
   logs.push(...packageContracts.logs);
   decisions.push(...packageContracts.decisions);
+  classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions });
 
   for (const pluginManifest of fixtureReport.pluginManifests) {
     const providerAuthKeys = Object.keys(pluginManifest.providerAuthEnvVars ?? {});
@@ -557,6 +679,45 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   return { warnings, suggestions, logs, decisions };
 }
 
+function classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions }) {
+  for (const securityManifest of fixtureReport.securityManifests ?? []) {
+    warnings.push({
+      fixture: fixture.id,
+      code: "unrecognized-security-manifest",
+      level: "warning",
+      message:
+        "openclaw.security.json is not a supported OpenClaw or ClawHub security contract and is ignored by install safety checks",
+      evidence: [securityManifest.path],
+    });
+    decisions.push({
+      fixture: fixture.id,
+      decision: "plugin-upstream-fix",
+      seam: "security-metadata",
+      action:
+        "Remove the advisory security manifest or replace it with a supported, versioned OpenClaw/ClawHub security contract once one exists.",
+      evidence: securityManifest.path,
+    });
+
+    if (securityManifest.schema === unavailableSecurityManifestSchema) {
+      warnings.push({
+        fixture: fixture.id,
+        code: "security-manifest-schema-unavailable",
+        level: "warning",
+        message: "openclaw.security.json references an OpenClaw schema URL that is not currently published",
+        evidence: [`${securityManifest.path}:$schema=${securityManifest.schema}`],
+      });
+      decisions.push({
+        fixture: fixture.id,
+        decision: "plugin-upstream-fix",
+        seam: "security-metadata",
+        action:
+          "Do not rely on the schema URL until OpenClaw publishes and documents a real plugin security metadata schema.",
+        evidence: securityManifest.schema,
+      });
+    }
+  }
+}
+
 function registrationCaptureGapDetails(inspection, targetOpenClaw) {
   const apiRegistrationDetails = inspection.registrationDetails.filter((registration) =>
     registration.name.startsWith("register"),
@@ -787,6 +948,235 @@ function selectPrimaryPackage(packages) {
   return packages[0] ?? null;
 }
 
+function summarizeOpenClawInstall(install) {
+  if (!install || typeof install !== "object") {
+    return null;
+  }
+  return {
+    clawhubSpec: stringOrNull(install.clawhubSpec),
+    npmSpec: stringOrNull(install.npmSpec),
+    defaultChoice: stringOrNull(install.defaultChoice),
+    minHostVersion: stringOrNull(install.minHostVersion),
+  };
+}
+
+function summarizeOpenClawRelease(release) {
+  if (!release || typeof release !== "object") {
+    return null;
+  }
+  return {
+    publishToClawHub: booleanOrNull(release.publishToClawHub),
+    publishToNpm: booleanOrNull(release.publishToNpm),
+  };
+}
+
+function unsupportedOpenClawPackageMetadata(openclaw) {
+  if (!openclaw || typeof openclaw !== "object") {
+    return [];
+  }
+  return Object.keys(openclaw)
+    .filter((key) => key === "bundle")
+    .map((key) => `openclaw.${key}`);
+}
+
+function summarizeNpmPack(packageJson, openclaw) {
+  const files = arrayValues(packageJson.files).map(normalizePackagePath).filter((item) => item.length > 0);
+  return {
+    advertised: openclaw?.release?.publishToNpm === true || nonEmptyString(openclaw?.install?.npmSpec),
+    private: packageJson.private === true,
+    filesMode: files.length > 0 ? "allowlist" : "implicit",
+    files,
+    invalidFileSpecs: files.filter((item) => invalidPackageFileSpec(item)),
+  };
+}
+
+function packageInstallMetadataIssues(packageSummary) {
+  const openclaw = packageSummary.openclaw;
+  if (!openclaw) {
+    return [];
+  }
+
+  const issues = [];
+  const install = openclaw.install;
+  const release = openclaw.release;
+  const publishToClawHub = release?.publishToClawHub === true;
+  const publishToNpm = release?.publishToNpm === true;
+
+  if (publishToClawHub && !nonEmptyString(install?.clawhubSpec)) {
+    issues.push("openclaw.release.publishToClawHub requires openclaw.install.clawhubSpec");
+  }
+  if (publishToNpm && !nonEmptyString(install?.npmSpec)) {
+    issues.push("openclaw.release.publishToNpm requires openclaw.install.npmSpec");
+  }
+  if (publishToNpm && nonEmptyString(install?.npmSpec) && nonEmptyString(packageSummary.name) && install.npmSpec !== packageSummary.name) {
+    issues.push(`openclaw.install.npmSpec:${install.npmSpec} does not match package name:${packageSummary.name}`);
+  }
+  if (nonEmptyString(install?.defaultChoice) && !["clawhub", "npm"].includes(install.defaultChoice)) {
+    issues.push(`openclaw.install.defaultChoice:${install.defaultChoice} must be clawhub or npm`);
+  }
+  if (install?.defaultChoice === "clawhub" && !nonEmptyString(install.clawhubSpec)) {
+    issues.push("openclaw.install.defaultChoice clawhub requires openclaw.install.clawhubSpec");
+  }
+  if (install?.defaultChoice === "npm" && !nonEmptyString(install.npmSpec)) {
+    issues.push("openclaw.install.defaultChoice npm requires openclaw.install.npmSpec");
+  }
+
+  return issues;
+}
+
+function packageNpmPackIssues(packageSummary, fixtureReport) {
+  if (!packageSummary.npmPack?.advertised) {
+    return [];
+  }
+
+  const findings = [];
+  const unavailable = [];
+  if (packageSummary.npmPack.private) {
+    unavailable.push("package.json private:true");
+  }
+  if (!nonEmptyString(packageSummary.name)) {
+    unavailable.push("package.json name missing");
+  }
+  if (!nonEmptyString(packageSummary.version)) {
+    unavailable.push("package.json version missing");
+  }
+  unavailable.push(...packageSummary.npmPack.invalidFileSpecs.map((item) => `invalid files entry:${item}`));
+
+  if (unavailable.length > 0) {
+    findings.push({
+      code: "package-npm-pack-unavailable",
+      message: "package advertises npm install or publish metadata but cannot produce a usable npm pack artifact",
+      evidence: unavailable,
+    });
+  }
+
+  const missingMetadata = packageNpmPackMissingMetadata(packageSummary, fixtureReport);
+  if (missingMetadata.length > 0) {
+    findings.push({
+      code: "package-npm-pack-metadata-missing",
+      message: "advertised npm artifact would not include required OpenClaw package metadata",
+      evidence: missingMetadata,
+    });
+  }
+
+  const missingEntrypoints = packageSummary.openclaw?.entrypoints
+    .filter((entrypoint) => !repoPathIncludedInNpmPack(packageSummary, entrypoint.relativePath))
+    .map((entrypoint) => `${entrypoint.kind}:${entrypoint.specifier} -> ${entrypoint.relativePath}`) ?? [];
+  if (missingEntrypoints.length > 0) {
+    findings.push({
+      code: "package-npm-pack-entrypoint-missing",
+      message: "advertised npm artifact would not include declared OpenClaw entrypoints",
+      evidence: missingEntrypoints,
+    });
+  }
+
+  return findings;
+}
+
+function packageNpmPackMissingMetadata(packageSummary, fixtureReport) {
+  const missing = [];
+  if (!repoPathIncludedInNpmPack(packageSummary, packageSummary.path)) {
+    missing.push(packageSummary.path);
+  }
+
+  for (const manifest of fixtureReport.pluginManifests ?? []) {
+    if (repoPathWithinPackage(packageSummary, manifest.path) && !repoPathIncludedInNpmPack(packageSummary, manifest.path)) {
+      missing.push(manifest.path);
+    }
+  }
+
+  return missing;
+}
+
+function packageMinHostVersionDrift(packageSummary) {
+  const openclaw = packageSummary.openclaw;
+  if (!nonEmptyString(openclaw?.install?.minHostVersion) || !nonEmptyString(openclaw?.buildOpenClawVersion)) {
+    return false;
+  }
+  return parseMinHostVersionFloor(openclaw.install.minHostVersion) !== openclaw.buildOpenClawVersion;
+}
+
+function parseMinHostVersionFloor(value) {
+  const match = /^>=([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function repoPathIncludedInNpmPack(packageSummary, repoPath) {
+  const packageRelativePath = packageRelativeRepoPath(packageSummary, repoPath);
+  if (!packageRelativePath) {
+    return false;
+  }
+  if (npmAlwaysPacksPath(packageRelativePath)) {
+    return true;
+  }
+  if (packageSummary.npmPack?.filesMode !== "allowlist") {
+    return true;
+  }
+  return packageSummary.npmPack.files.some((spec) => packageFileSpecIncludesPath(spec, packageRelativePath));
+}
+
+function repoPathWithinPackage(packageSummary, repoPath) {
+  return packageRelativeRepoPath(packageSummary, repoPath) !== null;
+}
+
+function packageRelativeRepoPath(packageSummary, repoPath) {
+  const packageDir = path.posix.dirname(normalizeRepoPath(packageSummary.path));
+  const normalized = normalizeRepoPath(repoPath);
+  if (packageDir === ".") {
+    return normalized;
+  }
+  if (normalized === packageDir) {
+    return "";
+  }
+  return normalized.startsWith(`${packageDir}/`) ? normalized.slice(packageDir.length + 1) : null;
+}
+
+function npmAlwaysPacksPath(packageRelativePath) {
+  const base = path.posix.basename(packageRelativePath).toLowerCase();
+  return packageRelativePath === "package.json" || /^readme(?:\..*)?$/u.test(base) || /^licen[cs]e(?:\..*)?$/u.test(base);
+}
+
+function packageFileSpecIncludesPath(spec, packageRelativePath) {
+  if (spec === "." || spec === packageRelativePath) {
+    return true;
+  }
+  if (spec.includes("*")) {
+    return globLikeSpecIncludesPath(spec, packageRelativePath);
+  }
+  return packageRelativePath.startsWith(`${spec.replace(/\/$/u, "")}/`);
+}
+
+function globLikeSpecIncludesPath(spec, packageRelativePath) {
+  return globSegmentsIncludePath(spec.split("/"), packageRelativePath.split("/"));
+}
+
+function globSegmentsIncludePath(specSegments, packageSegments) {
+  if (specSegments.length === 0) {
+    return packageSegments.length === 0;
+  }
+  const [head, ...tail] = specSegments;
+  if (head === "**") {
+    return globSegmentsIncludePath(tail, packageSegments) || (packageSegments.length > 0 && globSegmentsIncludePath(specSegments, packageSegments.slice(1)));
+  }
+  if (packageSegments.length === 0) {
+    return false;
+  }
+  return globSegmentIncludesPath(head, packageSegments[0]) && globSegmentsIncludePath(tail, packageSegments.slice(1));
+}
+
+function globSegmentIncludesPath(specSegment, packageSegment) {
+  const escaped = specSegment.replace(/[.+?^${}()|[\]\\]/gu, "\\$&").replaceAll("*", ".*");
+  return new RegExp(`^${escaped}$`, "u").test(packageSegment);
+}
+
+function invalidPackageFileSpec(spec) {
+  return spec.startsWith("/") || spec === ".." || spec.startsWith("../") || spec.includes("/../");
+}
+
+function normalizePackagePath(value) {
+  return normalizeRepoPath(value).replace(/^\.\/+/u, "").replace(/\/$/u, "");
+}
+
 function packageRank(packageSummary) {
   if (packageSummary.openclaw?.entrypoints.length > 0) {
     return 0;
@@ -801,6 +1191,22 @@ function arrayValues(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
 
+function stringOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+
+function booleanOrNull(value) {
+  return typeof value === "boolean" ? value : null;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function normalizeRepoPath(value) {
+  return String(value ?? "").replaceAll("\\", "/").replace(/^\.\/+/u, "");
+}
+
 function detailEvidence(details, key = "name") {
   return unique(details.map((detail) => `${detail[key]} @ ${detail.ref}`));
 }