@adea-ai/plugins 4.0.1 → 4.0.7

package/src/integrity-manifest.ts

@@ -1,44 +1,64 @@
 import { z } from 'zod'
-import { DIGEST_RE } from './schema.js'
+import { isPublishedName } from './publication.js'
+import { CatalogSchema, DIGEST_RE } from './schema.js'
+
+/** A mirrored brand mark published beside the artifacts. */
+export const PublishedAssetSchema = z.object({
+  name: z.string(),
+  digest: z.string().regex(DIGEST_RE),
+  bytes: z.number().int().positive(),
+  contentType: z.string(),
+  /** `content` mirrors a plugin file; `favicon` mirrors the product site's icon. */
+  kind: z.enum(['content', 'favicon']),
+  /** Upstream path or URL the bytes came from, for provenance. */
+  origin: z.string(),
+})
+export type PublishedAsset = Readonly<z.output<typeof PublishedAssetSchema>>
+
+/** The integrity record for a mirrored mark, from its catalog-relative path or site URL. */
+export function publishedAssetOf(icon: {
+  readonly asset: string
+  readonly digest: string
+  readonly bytes: number
+  readonly contentType: string
+  readonly kind: 'content' | 'favicon'
+  readonly path?: string | null
+  readonly url?: string | null
+}): PublishedAsset {
+  return {
+    name: icon.asset,
+    digest: icon.digest,
+    bytes: icon.bytes,
+    contentType: icon.contentType,
+    kind: icon.kind,
+    origin: (icon.kind === 'content' ? icon.path : icon.url) ?? '',
+  }
+}
 
 // Assets were added after the first v1 snapshots, so their absence remains valid.
 const IntegrityManifestSchema = z.object({
   schemaVersion: z.literal(1),
-  catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
+  catalogId: CatalogSchema.shape.catalogId,
   files: z.record(z.string(), z.string().regex(DIGEST_RE)),
-  assets: z
-    .array(
-      z.object({
-        name: z.string(),
-        digest: z.string().regex(DIGEST_RE),
-        bytes: z.number().int().positive(),
-        contentType: z.string(),
-        kind: z.enum(['content', 'favicon']),
-        origin: z.string(),
-      })
-    )
-    .optional(),
+  assets: z.array(PublishedAssetSchema).optional(),
 })
+type IntegrityManifest = z.output<typeof IntegrityManifestSchema>
 
 /** Validate all names before using a manifest to address local files or URLs. */
-export function parseIntegrityManifest(input: unknown) {
+export function parseIntegrityManifest(input: unknown): IntegrityManifest {
   const parsed = IntegrityManifestSchema.safeParse(input)
   if (!parsed.success || Object.keys(parsed.data.files).length === 0)
     throw new Error('INTEGRITY_MANIFEST_INVALID')
   const manifest = parsed.data
   for (const name of Object.keys(manifest.files)) {
-    if (!safeName(name) || name === 'integrity.json')
+    if (!isPublishedName(name) || name === 'integrity.json')
       throw new Error(`INTEGRITY_FILE_NAME_INVALID: ${name}`)
   }
   const assetNames = new Set<string>()
   for (const asset of manifest.assets ?? []) {
-    if (!safeName(asset.name)) throw new Error(`INTEGRITY_ASSET_NAME_INVALID: ${asset.name}`)
+    if (!isPublishedName(asset.name)) throw new Error(`INTEGRITY_ASSET_NAME_INVALID: ${asset.name}`)
     if (assetNames.has(asset.name)) throw new Error(`INTEGRITY_ASSET_DUPLICATE: ${asset.name}`)
     assetNames.add(asset.name)
   }
   return manifest
 }
-
-function safeName(name: string): boolean {
-  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(name)
-}

package/src/json-values.ts

@@ -0,0 +1,11 @@
+export function stringValue(input: unknown): string | undefined {
+  return typeof input === 'string' && input.trim() ? input.trim() : undefined
+}
+
+export function isString(input: unknown): input is string {
+  return typeof input === 'string' && input.trim().length > 0
+}
+
+export function arrayValue(input: unknown): unknown[] {
+  return Array.isArray(input) ? input : []
+}

package/src/plugin-release.ts

@@ -0,0 +1,457 @@
+import { byteDigest, digest, sourceDigest } from './digest.js'
+import {
+  capabilitySummary,
+  classifyCapabilities,
+  createCompatibility,
+  createSecurity,
+} from './capabilities.js'
+import { normalizeDisplayName } from './display-name.js'
+import { stageIconBytes } from './icon-mirror.js'
+import {
+  iconAssetName,
+  iconOverrideFor,
+  inspectIconBytes,
+  selectIconPath,
+  type ProductIconOverrides,
+} from './icons.js'
+import { arrayValue, isString, stringValue } from './json-values.js'
+import { PluginSafetyError } from './plugin-skips.js'
+import type { CatalogPolicy } from './policy.js'
+import type {
+  Capability,
+  Harness,
+  HarnessCompatibility,
+  LicenseMetadata,
+  Plugin,
+  PluginProvenance,
+  PluginRelease,
+} from './schema.js'
+import { isVendorHomepage, resolveSiteIcon, type SiteIcon } from './site-icons.js'
+import type { Snapshot, SnapshotLoader } from './snapshots.js'
+import {
+  resolvePluginSource,
+  type ResolvedPluginSource,
+  type ResolvedSource,
+} from './source-resolution.js'
+import {
+  canonicalRepositoryUrl,
+  parseJsonDocument,
+  safeRelativePath,
+  type MarketplacePluginEntry,
+} from './sources.js'
+import {
+  normalizeCategory,
+  productGroupingKey,
+  stablePluginId,
+  stableReleaseId,
+  type CategoryMap,
+  type ProductAliases,
+} from './taxonomy.js'
+import { createSiteIconFetcher, SITE_FETCH_TIMEOUT_MS } from './upstream.js'
+
+/**
+ * Marks the catalog format this compiler emits.
+ *
+ * Bumping or first introducing this value makes a synchronization replay its
+ * verified pins and rebuild, which is how a format change reaches the published
+ * catalog when no upstream source has moved. It is deliberately separate from
+ * the agent-package normalizer version, which describes package normalization
+ * and would misreport a change here.
+ */
+export const CATALOG_CONTRACT_VERSION = 'adea-catalog/3'
+
+/** Trusted compiler extension; never loaded from upstream plugin content. */
+export type ReleaseTransform = (
+  release: PluginRelease,
+  snapshot: Snapshot,
+  pluginName: string
+) => PluginRelease
+
+/** Everything that shapes a release besides the marketplace entry itself. */
+export interface ReleaseOptions {
+  readonly categoryMap: CategoryMap
+  readonly productCategories?: Record<string, string>
+  readonly productAliases: ProductAliases
+  readonly productIconOverrides?: ProductIconOverrides
+  /** Directory that receives mirrored brand marks as the catalog is built. */
+  readonly iconAssetsDirectory?: string
+  readonly policy: CatalogPolicy
+  readonly metadataOnly: boolean
+  readonly snapshotLoader: SnapshotLoader
+  /** Live builds resolve unpinned refs and may fetch vendor site icons. */
+  readonly resolveExternalRefs: boolean
+  readonly transformRelease?: ReleaseTransform
+  /** Compatibility derived from the final release, replacing the dialect heuristic. */
+  readonly releaseCompatibility?: ReleaseCompatibility
+}
+
+export type ReleaseCompatibility = (
+  release: PluginRelease
+) => Record<Harness, HarnessCompatibility> | undefined
+
+export async function normalizePlugin(
+  source: ResolvedSource,
+  entry: MarketplacePluginEntry,
+  input: ReleaseOptions
+): Promise<Plugin> {
+  const { policy } = input
+  const resolved = await resolvePluginSource(
+    entry.name,
+    entry.source,
+    source,
+    input.resolveExternalRefs
+  )
+  const snapshot = input.metadataOnly
+    ? { files: new Map<string, Uint8Array>(), symlinks: [] }
+    : await input.snapshotLoader.load(
+        resolved.repositoryUrl,
+        resolved.commitSha,
+        resolved.subdirectory
+      )
+  if (snapshot.symlinks.length > 0)
+    throw new PluginSafetyError('SYMLINK_ESCAPE', [...snapshot.symlinks].toSorted())
+  validateSnapshot(snapshot, policy, entry.name)
+  const contentDigest = input.metadataOnly
+    ? digest({
+        repositoryUrl: resolved.repositoryUrl,
+        subdirectory: resolved.subdirectory,
+        commitSha: resolved.commitSha,
+        entryDigest: entry.entryDigest,
+      })
+    : sourceDigest(snapshot.files)
+  const pluginManifest = findPluginManifest(snapshot)
+  const manifestDigest = pluginManifest ? digest(pluginManifest.metadata) : entry.entryDigest
+  const capabilities = classifyCapabilities(snapshot.files, pluginManifest?.metadata, policy)
+  const iconOverride = iconOverrideFor(
+    input.productIconOverrides,
+    productGroupingKey(entry.name, input.productAliases)
+  )
+  const contentIcon = resolveContentIcon(snapshot, iconOverride, input.metadataOnly)
+  const favicon =
+    contentIcon === undefined
+      ? await resolveFavicon({
+          entry,
+          iconOverride,
+          metadataOnly: input.metadataOnly,
+          live: input.resolveExternalRefs,
+        })
+      : undefined
+  // Stage the mark while its bytes are in hand. Publication then needs no
+  // re-fetch, and a site icon cannot drift between resolution and release.
+  const mark = contentIcon
+    ? { ...contentIcon, bytes: snapshot.files.get(contentIcon.path) }
+    : favicon
+  if (input.iconAssetsDirectory && mark?.bytes)
+    await stageIconBytes(
+      input.iconAssetsDirectory,
+      iconAssetName(mark.digest, mark.contentType),
+      mark.bytes
+    )
+  const releaseId = stableReleaseId(
+    resolved.repositoryUrl,
+    resolved.subdirectory,
+    resolved.commitSha,
+    contentDigest
+  )
+  const originalRelease = createRelease({
+    source,
+    entry,
+    resolved,
+    contentDigest,
+    manifestDigest,
+    capabilities,
+    snapshot,
+    ...(pluginManifest ? { pluginManifest } : {}),
+    releaseId,
+    ...(contentIcon ? { contentIcon } : {}),
+    ...(favicon ? { favicon } : {}),
+    metadataOnly: input.metadataOnly,
+  })
+  const release =
+    input.transformRelease && !input.metadataOnly
+      ? input.transformRelease(originalRelease, snapshot, entry.name)
+      : originalRelease
+  const compatibility =
+    input.releaseCompatibility?.(release) ??
+    createCompatibility(source.config.marketplaceDialect, capabilities, policy)
+  const security = createSecurity(capabilities, policy, input.metadataOnly)
+  const normalizedCategories = entry.categories.map((category) =>
+    normalizeCategory(category, input.categoryMap)
+  )
+  const productCategory = input.productCategories?.[entry.name]
+  const categories = [
+    ...new Set(
+      (productCategory
+        ? [productCategory, ...normalizedCategories.filter((category) => category !== 'other')]
+        : normalizedCategories.length > 0
+          ? normalizedCategories
+          : [input.categoryMap.fallback]
+      ).filter(Boolean)
+    ),
+  ].toSorted()
+  // The name a list renders: marketplace manifests are inconsistent (`Gmail`
+  // beside `zapier` beside `aws-agents-for-devsecops`), so the catalog
+  // publishes the written form once and every consumer shows the same thing.
+  const displayName = normalizeDisplayName(
+    entry.displayName ?? pluginManifest?.displayName ?? entry.name
+  )
+  const authors =
+    entry.authors.length > 0
+      ? [...entry.authors]
+      : source.parsed.owner.length > 0
+        ? [...source.parsed.owner]
+        : ['Unknown']
+  const keywords = [...new Set([...entry.keywords, ...entry.name.split(/[-_\s]+/g), ...categories])]
+    .filter(Boolean)
+    .toSorted()
+  const provenance: PluginProvenance = {
+    sourceId: source.config.sourceId,
+    repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
+    manifestPath: source.config.manifestPath,
+    pluginSubdirectory: resolved.subdirectory || '.',
+    resolvedCommitSha: resolved.commitSha,
+    sourceManifestDigest: source.manifestDigest,
+    upstreamEntryDigest: entry.entryDigest,
+  }
+  return {
+    pluginId: stablePluginId(source.config.sourceId, entry.name),
+    displayName,
+    description: entry.description || pluginManifest?.description || '',
+    productGroupingKey: productGroupingKey(entry.name, input.productAliases),
+    categories,
+    keywords,
+    authors,
+    ...(entry.homepage ? { homepage: entry.homepage } : {}),
+    icons: entry.icons.length > 0 ? [...entry.icons].toSorted() : (pluginManifest?.icons ?? []),
+    sourceId: source.config.sourceId,
+    upstreamPluginName: entry.name,
+    currentReleaseId: releaseId,
+    availableReleases: [release],
+    capabilitySummary: capabilitySummary(capabilities),
+    harnessCompatibility: compatibility,
+    license: findLicense(entry, pluginManifest?.metadata),
+    provenance,
+    securityClassification: security,
+  }
+}
+
+interface CreateReleaseInput {
+  readonly source: ResolvedSource
+  readonly entry: MarketplacePluginEntry
+  readonly resolved: ResolvedPluginSource
+  readonly contentDigest: string
+  readonly manifestDigest: string
+  readonly capabilities: readonly Capability[]
+  readonly snapshot: Snapshot
+  readonly pluginManifest?: PluginManifest
+  readonly releaseId: string
+  readonly contentIcon?: PluginRelease['icon'] | undefined
+  readonly favicon?: SiteIcon | undefined
+  readonly metadataOnly: boolean
+}
+
+function createRelease(input: CreateReleaseInput): PluginRelease {
+  const requiredCredentials = new Set<string>()
+  const auth = input.entry.policy.authentication
+  if (typeof auth === 'string' && auth !== 'NONE' && auth !== 'DISABLED')
+    requiredCredentials.add('authentication')
+  for (const value of arrayValue(input.entry.raw.requiredCredentials))
+    if (typeof value === 'string') requiredCredentials.add(value)
+  const requiredConnectors = [
+    ...new Set(arrayValue(input.entry.raw.connectors).filter(isString)),
+  ].toSorted()
+  const permissionSensitiveChanges = input.capabilities
+    .filter((capability) => capability.securityImpact === 'sensitive')
+    .map((capability) => capability.type)
+    .toSorted()
+  const metadata: Record<string, unknown> = {
+    catalogContract: CATALOG_CONTRACT_VERSION,
+    marketplaceEntry: input.entry.raw,
+    ...(input.pluginManifest ? { pluginManifest: input.pluginManifest.metadata } : {}),
+    sourceDialect: input.source.config.marketplaceDialect,
+  }
+  const version = input.pluginManifest?.version ?? stringValue(input.entry.raw.version)
+  return {
+    releaseId: input.releaseId,
+    ...(version ? { upstreamVersion: version } : {}),
+    resolvedRepositoryUrl: input.resolved.repositoryUrl,
+    resolvedCommitSha: input.resolved.commitSha,
+    pluginSubdirectory: input.resolved.subdirectory || '.',
+    canonicalContentDigest: input.contentDigest,
+    manifestDigest: input.manifestDigest,
+    contentResolution: input.metadataOnly ? 'metadata-only' : 'complete',
+    releaseMetadata: metadata,
+    capabilities: [...input.capabilities].toSorted(
+      (left, right) => left.type.localeCompare(right.type) || left.name.localeCompare(right.name)
+    ),
+    requiredConnectors,
+    requiredCredentials: [...requiredCredentials].toSorted(),
+    permissionSensitiveChanges: [...new Set(permissionSensitiveChanges)],
+    fileIndex: [...input.snapshot.files.keys()].toSorted(),
+    publicationTimestamp: input.source.retrievedAt,
+    ...assembleIcon(input),
+  }
+}
+
+/**
+ * Resolves the product site's icon, for a plugin whose content ships no mark.
+ *
+ * Only a live build with complete content attempts this: a metadata-only or
+ * offline run must not reach out to vendor sites, and neither may a product the
+ * curator has already decided about.
+ */
+async function resolveFavicon(input: {
+  readonly entry: MarketplacePluginEntry
+  readonly iconOverride?: IconOverride | undefined
+  readonly metadataOnly: boolean
+  readonly live: boolean
+}): Promise<SiteIcon | undefined> {
+  if (!input.live || input.metadataOnly) return undefined
+  if (input.iconOverride?.forced === null || input.iconOverride?.forced) return undefined
+  const homepage = input.iconOverride?.site ?? input.entry.homepage
+  if (!isVendorHomepage(homepage)) return undefined
+  // Bound both fetches: a vendor site that never answers must not stall a
+  // catalogue build. A timeout simply leaves the product on its monogram.
+  const signal = AbortSignal.timeout(SITE_FETCH_TIMEOUT_MS)
+  const resolved = await resolveSiteIcon(homepage!, createSiteIconFetcher(signal))
+  return 'contentType' in resolved ? resolved : undefined
+}
+
+/**
+ * Picks and vets the brand mark for a release.
+ *
+ * A file in the plugin's own content is preferred, because it is the mark the
+ * vendor ships with the plugin. When the content has none, a live build falls
+ * back to the declared homepage's site icon: many plugins are a thin wrapper
+ * over a vendor API and point at the vendor's site rather than shipping a logo.
+ * Whatever the source, an icon that fails inspection is absent rather than
+ * advertised: the catalog never publishes content it would refuse to mirror.
+ */
+function resolveContentIcon(
+  snapshot: Snapshot,
+  iconOverride: IconOverride | undefined,
+  metadataOnly: boolean
+): ContentIcon | undefined {
+  if (metadataOnly || snapshot.files.size === 0) return undefined
+  // A curator override wins over every rule, including "publish no icon".
+  if (iconOverride?.forced === null) return undefined
+  const files = [...snapshot.files.keys()].toSorted()
+  const forced = iconOverride?.forced
+  if (forced && !files.includes(forced)) return undefined
+  const path = forced ?? selectIconPath(files)
+  if (!path) return undefined
+  const bytes = snapshot.files.get(path)
+  if (!bytes) return undefined
+  const inspected = inspectIconBytes(bytes)
+  if (!('contentType' in inspected)) return undefined
+  return {
+    kind: 'content',
+    path,
+    contentType: inspected.contentType,
+    digest: byteDigest(bytes),
+    bytes: bytes.byteLength,
+  }
+}
+
+type IconOverride = ReturnType<typeof iconOverrideFor>
+type ContentIcon = Extract<NonNullable<PluginRelease['icon']>, { kind: 'content' }>
+
+function assembleIcon(
+  input: Pick<CreateReleaseInput, 'contentIcon' | 'favicon'>
+): { icon: NonNullable<PluginRelease['icon']> } | Record<string, never> {
+  if (input.contentIcon) return { icon: input.contentIcon }
+  if (input.favicon)
+    return {
+      icon: {
+        kind: 'favicon',
+        url: input.favicon.url,
+        homepage: input.favicon.homepage,
+        contentType: input.favicon.contentType,
+        digest: input.favicon.digest,
+        bytes: input.favicon.bytes.byteLength,
+      },
+    }
+  return {}
+}
+
+function validateSnapshot(snapshot: Snapshot, policy: CatalogPolicy, pluginName: string): void {
+  if (snapshot.files.size > policy.maxFilesPerPlugin)
+    throw new PluginSafetyError('PLUGIN_TOO_MANY_FILES', [pluginName])
+  let total = 0
+  for (const [path, bytes] of snapshot.files) {
+    try {
+      safeRelativePath(path, 'SNAPSHOT_PATH_INVALID')
+    } catch {
+      throw new PluginSafetyError('SNAPSHOT_PATH_INVALID', [path])
+    }
+    if (bytes.byteLength > policy.maxFileBytes)
+      throw new PluginSafetyError('PLUGIN_FILE_TOO_LARGE', [path])
+    total += bytes.byteLength
+  }
+  if (total > policy.maxBytesPerPlugin)
+    throw new PluginSafetyError('PLUGIN_TOO_LARGE', [pluginName])
+}
+
+interface PluginManifest {
+  readonly metadata: Record<string, unknown>
+  readonly displayName?: string | undefined
+  readonly description?: string | undefined
+  readonly version?: string | undefined
+  readonly icons: string[]
+}
+
+function findPluginManifest(snapshot: Snapshot): PluginManifest | undefined {
+  const candidates = [...snapshot.files.keys()]
+    .filter((path) => {
+      const lower = path.toLocaleLowerCase()
+      return lower === 'plugin.json' || lower.endsWith('/plugin.json') || lower === 'package.json'
+    })
+    .toSorted(
+      (left, right) => manifestRank(left) - manifestRank(right) || left.localeCompare(right)
+    )
+  const path = candidates[0]
+  if (!path) return undefined
+  try {
+    const bytes = snapshot.files.get(path)
+    if (!bytes) return undefined
+    const metadata = parseJsonDocument(new TextDecoder().decode(bytes)) as Record<string, unknown>
+    return {
+      metadata,
+      ...((stringValue(metadata.displayName) ?? stringValue(metadata.name))
+        ? { displayName: stringValue(metadata.displayName) ?? stringValue(metadata.name) }
+        : {}),
+      ...(stringValue(metadata.description)
+        ? { description: stringValue(metadata.description) }
+        : {}),
+      ...(stringValue(metadata.version) ? { version: stringValue(metadata.version) } : {}),
+      icons: [metadata.icon, ...(Array.isArray(metadata.icons) ? metadata.icons : [])]
+        .filter(isString)
+        .toSorted(),
+    }
+  } catch {
+    throw new PluginSafetyError('PLUGIN_MANIFEST_INVALID', [path])
+  }
+}
+
+function manifestRank(path: string): number {
+  // A root manifest is the plugin's own declaration and outranks harness copies.
+  if (path === 'plugin.json') return -1
+  const lower = path.toLocaleLowerCase()
+  if (lower.endsWith('/.claude-plugin/plugin.json')) return 0
+  if (lower.endsWith('/.cursor-plugin/plugin.json')) return 1
+  if (lower.endsWith('/.agents/plugin.json')) return 2
+  return lower === 'plugin.json' ? 3 : 4
+}
+
+function findLicense(
+  entry: MarketplacePluginEntry,
+  metadata?: Record<string, unknown>
+): LicenseMetadata {
+  const candidate = stringValue(metadata?.license) ?? stringValue(entry.raw.license)
+  if (!candidate) return { name: 'Unknown', source: 'unknown' }
+  return {
+    name: candidate,
+    ...(candidate.startsWith('http') ? { url: candidate } : {}),
+    source: metadata?.license !== undefined ? 'plugin-manifest' : 'marketplace-entry',
+  }
+}

package/src/plugin-skips.ts

@@ -0,0 +1,110 @@
+import type { MarketplacePluginEntry } from './sources.js'
+import type { ResolvedSource } from './source-resolution.js'
+import { stablePluginId } from './taxonomy.js'
+
+export type PluginSkipReasonCode =
+  | 'GIT_SUBMODULE_UNSUPPORTED'
+  | 'PLUGIN_FILE_TOO_LARGE'
+  | 'PLUGIN_FILE_UNAVAILABLE'
+  | 'PLUGIN_MANIFEST_INVALID'
+  | 'PLUGIN_PATH_NOT_FOUND'
+  | 'PLUGIN_SCHEMA_INVALID'
+  | 'PLUGIN_SIZE_POLICY'
+  | 'PLUGIN_SOURCE_UNAVAILABLE'
+  | 'PLUGIN_TOO_LARGE'
+  | 'PLUGIN_TOO_MANY_FILES'
+  | 'SNAPSHOT_PATH_INVALID'
+  | 'SYMLINK_ESCAPE'
+
+export interface SkippedPlugin {
+  readonly sourceId: string
+  readonly pluginId: string
+  readonly pluginName: string
+  readonly reasonCode: PluginSkipReasonCode
+  readonly securityReason: string
+  readonly incompleteContent: true
+  readonly paths: readonly string[]
+}
+
+export class PluginSafetyError extends Error {
+  constructor(
+    readonly reasonCode: PluginSkipReasonCode,
+    readonly paths: readonly string[]
+  ) {
+    super(`${reasonCode}${paths.length > 0 ? `: ${paths.join(',')}` : ''}`)
+    this.name = 'PluginSafetyError'
+  }
+}
+
+const pluginSkipReasons: Readonly<Record<PluginSkipReasonCode, string>> = {
+  GIT_SUBMODULE_UNSUPPORTED:
+    'The plugin contains a Git submodule, so the catalog excludes it rather than traversing an unpinned repository boundary.',
+  PLUGIN_FILE_TOO_LARGE:
+    'The plugin contains a file over the configured size limit, so the catalog excludes the plugin before publication.',
+  PLUGIN_FILE_UNAVAILABLE:
+    'A plugin file could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
+  PLUGIN_MANIFEST_INVALID:
+    'The plugin manifest is malformed, so the catalog excludes the plugin before consuming its metadata.',
+  PLUGIN_PATH_NOT_FOUND:
+    'The declared plugin path does not exist at the pinned commit, so the catalog excludes the plugin.',
+  PLUGIN_SCHEMA_INVALID:
+    'The normalized plugin record exceeds the published catalog schema, so the catalog excludes it before publication.',
+  PLUGIN_SIZE_POLICY:
+    'The plugin exceeds the configured size policy, so the catalog excludes it before publication.',
+  PLUGIN_SOURCE_UNAVAILABLE:
+    'The plugin repository tree could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
+  PLUGIN_TOO_LARGE:
+    'The plugin exceeds the configured aggregate size limit, so the catalog excludes it before publication.',
+  PLUGIN_TOO_MANY_FILES:
+    'The plugin exceeds the configured file-count limit, so the catalog excludes it before publication.',
+  SNAPSHOT_PATH_INVALID:
+    'The plugin snapshot contains an unsafe path, so the catalog excludes it rather than allowing repository escape.',
+  SYMLINK_ESCAPE:
+    'The plugin snapshot contains symlinks; symlinks are never followed, so the catalog excludes the plugin.',
+}
+
+export function createSkippedPlugin(
+  source: ResolvedSource,
+  entry: MarketplacePluginEntry,
+  error: unknown
+): SkippedPlugin | undefined {
+  const parsed =
+    error instanceof PluginSafetyError
+      ? { reasonCode: error.reasonCode, paths: error.paths }
+      : parsePluginSafetyError(error)
+  if (!parsed) return undefined
+  return {
+    sourceId: source.config.sourceId,
+    pluginId: stablePluginId(source.config.sourceId, entry.name),
+    pluginName: entry.name,
+    reasonCode: parsed.reasonCode,
+    securityReason: pluginSkipReasons[parsed.reasonCode],
+    incompleteContent: true,
+    paths: [...new Set(parsed.paths)].toSorted(),
+  }
+}
+
+function parsePluginSafetyError(
+  error: unknown
+): { reasonCode: PluginSkipReasonCode; paths: readonly string[] } | undefined {
+  const message = error instanceof Error ? error.message : String(error)
+  const match = /^([A-Z_]+)(?::\s?(.*))?$/.exec(message)
+  if (!match) return undefined
+  const reasonCode = match[1] as PluginSkipReasonCode
+  if (!(reasonCode in pluginSkipReasons)) return undefined
+  return {
+    reasonCode,
+    paths: match[2]
+      ? match[2]
+          .split(',')
+          .map((path) => path.trim())
+          .filter(Boolean)
+      : [],
+  }
+}
+
+export const UPSTREAM_WEATHER_SKIP_CODES: ReadonlySet<PluginSkipReasonCode> = new Set([
+  'PLUGIN_SOURCE_UNAVAILABLE',
+  'PLUGIN_FILE_UNAVAILABLE',
+  'PLUGIN_PATH_NOT_FOUND',
+])