@adea-ai/plugins 4.0.0 → 4.0.6

package/src/artifacts.test.ts

@@ -186,6 +186,15 @@ describe('artifact shards', () => {
     plugin({ sourceId: 'claude-official', name: 'sales', categories: ['business-operations'] }),
   ]
 
+  test('index options can change companion artifacts without changing the catalog ID', () => {
+    const base = catalog(plugins)
+    const first = createArtifacts(base, lockFor(plugins) as never, { topCount: 1 })
+    const second = createArtifacts(base, lockFor(plugins) as never, { topCount: 2 })
+    expect(first['catalog.v1.json']).toBe(second['catalog.v1.json'])
+    expect(first['catalog-index.v1.json']).not.toBe(second['catalog-index.v1.json'])
+    expect(first['integrity.json']).not.toBe(second['integrity.json'])
+  })
+
   test('publishes navigation, one index, and a shelf and list per category', () => {
     const { artifacts } = artifactsOf(plugins)
     const names = Object.keys(artifacts).toSorted()
@@ -478,6 +487,77 @@ describe('artifact shards', () => {
 })
 
 describe('icon mirroring', () => {
+  test('tries another pinned source when a shared icon cannot be fetched', async () => {
+    const { base, index } = artifactsOf([
+      plugin({
+        sourceId: 'cursor-official',
+        name: 'first',
+        categories: ['productivity'],
+        icon: { path: 'first/logo.svg', bytes: CLEAN_SVG },
+      }),
+      plugin({
+        sourceId: 'claude-official',
+        name: 'second',
+        categories: ['productivity'],
+        icon: { path: 'second/logo.svg', bytes: CLEAN_SVG },
+      }),
+    ])
+    const sources = resolveIconSources(base, index)
+    const directory = await mkdtemp(join(tmpdir(), 'adea-icons-fallback-'))
+    try {
+      const calls: string[] = []
+      const result = await stageIconAssets({
+        sources,
+        assetsDirectory: directory,
+        readBytes: async (source) => {
+          if (source.kind !== 'content') throw new Error('unexpected favicon')
+          calls.push(source.path)
+          if (source.path === 'first/logo.svg') throw new Error('source unavailable')
+          return CLEAN_SVG
+        },
+      })
+      expect(calls).toEqual(['first/logo.svg', 'second/logo.svg'])
+      expect(result.staged.map((asset) => asset.name)).toEqual([svgAsset])
+      expect(result.skipped).toEqual([])
+      expect(await fs.readFile(join(directory, svgAsset))).toEqual(Buffer.from(CLEAN_SVG))
+      await fs.rm(join(directory, svgAsset))
+      const successfulCalls: string[] = []
+      const successful = await stageIconAssets({
+        sources,
+        assetsDirectory: directory,
+        readBytes: async (source) => {
+          if (source.kind !== 'content') throw new Error('unexpected favicon')
+          successfulCalls.push(source.path)
+          return CLEAN_SVG
+        },
+      })
+      expect(successfulCalls).toEqual(['first/logo.svg'])
+      expect(successful.staged).toHaveLength(1)
+      expect(successful.skipped).toEqual([])
+      await fs.rm(join(directory, svgAsset))
+      const mismatched = await stageIconAssets({
+        sources,
+        assetsDirectory: directory,
+        readBytes: async (source) =>
+          source.kind === 'content' && source.path === 'first/logo.svg' ? OTHER_SVG : CLEAN_SVG,
+      })
+      expect(mismatched.staged.map((asset) => asset.name)).toEqual([svgAsset])
+      expect(mismatched.skipped).toEqual([])
+      await fs.rm(join(directory, svgAsset))
+      const failed = await stageIconAssets({
+        sources,
+        assetsDirectory: directory,
+        readBytes: async () => {
+          throw new Error('unavailable')
+        },
+      })
+      expect(failed.staged).toEqual([])
+      expect(failed.skipped).toEqual([{ asset: svgAsset, reason: 'FETCH_FAILED: unavailable' }])
+    } finally {
+      await fs.rm(directory, { recursive: true, force: true })
+    }
+  })
+
   test('resolves each asset to the commit it was published from', () => {
     const plugins = [
       plugin({

package/src/artifacts.ts

@@ -0,0 +1,234 @@
+import { publishCatalog, type PublishOptions } from './catalog-store.js'
+import {
+  buildConsumerIndex,
+  CATALOG_INDEX_ARTIFACT,
+  iconCoverage,
+  type ConsumerIndex,
+  type ProductPreference,
+} from './consumer-index.js'
+import { digest } from './digest.js'
+import { publishedAssetOf, type PublishedAsset } from './integrity-manifest.js'
+import { catalogIdSuffix, immutableAssetUrl } from './publication.js'
+import type { Catalog, SourcesLock } from './schema.js'
+
+/**
+ * Published artifacts by file name. The core six are always present; the
+ * consumer shards (`catalog-index.v1.json`, `shelf-<category>.v1.json` and
+ * `category-<category>.v1.json`) follow the configured categories.
+ */
+export interface GeneratedArtifacts {
+  readonly [name: string]: string
+  readonly 'catalog.v1.json': string
+  readonly 'catalog-summary.v1.json': string
+  readonly 'sources.lock.json': string
+  readonly 'compatibility.v1.json': string
+  readonly 'categories.v1.json': string
+  readonly 'integrity.json': string
+}
+
+export interface ConsumerIndexOptions {
+  readonly leading?: Readonly<Record<string, readonly string[]>>
+  readonly topCount?: number
+  readonly productPreference?: ProductPreference
+  /**
+   * Where this catalog is published. When known, product records carry an
+   * absolute, immutable URL for their brand mark so no client composes one.
+   */
+  readonly publicationRepositoryUrl?: string
+  /**
+   * Base URL of the committed asset directory that browsers fetch directly.
+   *
+   * GitHub release assets answer a cross-origin `fetch` with no CORS header and
+   * redirect through a URL that cannot be cached, so a browser neither reads the
+   * index nor reuses an icon. The same files served from the repository are
+   * CORS-enabled, direct and cacheable.
+   */
+  readonly publicationAssetsBaseUrl?: string
+  /**
+   * Base URL of the content-addressed snapshot directory, one level below the
+   * asset branch. Catalog artifacts are addressed by catalog identity, so they
+   * live in `catalogs/<catalogId>/` while digest-addressed brand marks sit at
+   * the branch root.
+   */
+  readonly publicationCatalogsBaseUrl?: string
+  /**
+   * Whether curated-name drift is published in the consumer index. An offline
+   * build replays fixtures rather than the upstream catalogs, so its curation
+   * findings are noise and are omitted by default.
+   */
+  readonly curationDiagnostics?: boolean
+}
+
+export function createArtifacts(
+  catalog: Catalog,
+  lock: SourcesLock,
+  options: ConsumerIndexOptions = {}
+): GeneratedArtifacts {
+  const index = buildConsumerIndex({ ...options, catalog })
+  const summary = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    generatedAt: catalog.generatedAt,
+    sourceCount: catalog.sources.length,
+    pluginCount: catalog.plugins.length,
+    categories: [...new Set(catalog.plugins.flatMap((plugin) => plugin.categories))].toSorted(),
+    productGroups: [
+      ...new Set(catalog.plugins.map((plugin) => plugin.productGroupingKey)),
+    ].toSorted(),
+    search: catalog.plugins
+      .map((plugin) => ({
+        pluginId: plugin.pluginId,
+        text: `${plugin.displayName} ${plugin.description} ${plugin.keywords.join(' ')}`.trim(),
+      }))
+      .toSorted((left, right) => left.pluginId.localeCompare(right.pluginId)),
+  }
+  const compatibility = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    plugins: catalog.plugins.map((plugin) => ({
+      pluginId: plugin.pluginId,
+      harnessCompatibility: plugin.harnessCompatibility,
+    })),
+  }
+  // Navigation stays small and points at the shards a client then fetches:
+  // `shelf-*` for a default view, `category-*` for "view more", and
+  // `catalog-index.v1.json` for the complete product list.
+  const navigation = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    generatedAt: catalog.generatedAt,
+    topCount: index.topCount,
+    sourcePreference: index.sourcePreference,
+    counts: index.counts,
+    catalogIndexArtifact: CATALOG_INDEX_ARTIFACT,
+    iconCoverage: iconCoverage(index),
+    // The index URL rides in the navigation artifact so a client can fetch the
+    // browsing index from the publication it was told about, verify it against
+    // the digest in integrity.json, and never compose a URL or need this
+    // service to proxy it. Absent for an unpublished build.
+    ...(options.publicationCatalogsBaseUrl
+      ? {
+          catalogIndexUrl: `${options.publicationCatalogsBaseUrl}/${catalogIdSuffix(catalog.catalogId)}/${CATALOG_INDEX_ARTIFACT}`,
+        }
+      : options.publicationAssetsBaseUrl
+        ? { catalogIndexUrl: `${options.publicationAssetsBaseUrl}/${CATALOG_INDEX_ARTIFACT}` }
+        : options.publicationRepositoryUrl
+          ? {
+              catalogIndexUrl: immutableAssetUrl(
+                options.publicationRepositoryUrl,
+                catalog.catalogId,
+                CATALOG_INDEX_ARTIFACT
+              ),
+            }
+          : {}),
+    // Marks ride in the navigation artifact so a client that already receives it
+    // renders compiled brand marks without fetching the browsing index. Keys are
+    // sorted for a stable artifact.
+    brandMarks: Object.fromEntries(
+      Object.keys(index.products)
+        .toSorted()
+        .flatMap((productKey) => {
+          const assetUrl = index.products[productKey]?.icon?.assetUrl
+          return assetUrl ? [[productKey, assetUrl] as const] : []
+        })
+    ),
+    categories: index.categories,
+    diagnostics: options.curationDiagnostics === false ? [] : index.diagnostics,
+  }
+  const shards: Record<string, string> = {
+    [CATALOG_INDEX_ARTIFACT]: json({
+      schemaVersion: 1,
+      catalogId: catalog.catalogId,
+      generatedAt: catalog.generatedAt,
+      topCount: index.topCount,
+      sourcePreference: index.sourcePreference,
+      counts: index.counts,
+      products: index.products,
+      categories: index.categories.map((category) => ({
+        category: category.category,
+        productCount: category.productCount,
+        productKeys: category.productKeys,
+      })),
+    }),
+  }
+  for (const category of index.categories) {
+    shards[category.shelfArtifact] = json({
+      schemaVersion: 1,
+      catalogId: catalog.catalogId,
+      category: category.category,
+      topCount: index.topCount,
+      products: category.topProductKeys.map((productKey) => index.products[productKey]),
+    })
+    shards[category.listArtifact] = json({
+      schemaVersion: 1,
+      catalogId: catalog.catalogId,
+      category: category.category,
+      productCount: category.productCount,
+      pluginCount: category.pluginCount,
+      products: category.productKeys.map((productKey) => index.products[productKey]),
+    })
+  }
+  const files: Record<string, string> = {
+    'catalog.v1.json': json(catalog),
+    'catalog-summary.v1.json': json(summary),
+    'sources.lock.json': json(lock),
+    'compatibility.v1.json': json(compatibility),
+    'categories.v1.json': json(navigation),
+    ...shards,
+  }
+  const integrityBody = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    // An artifact's digest is the canonical digest of its text, not a hash of
+    // the file bytes: consumers read the artifact as a string and compare it
+    // with `canonicalDigest`, so a checker hashing the raw bytes will disagree
+    // with every published release. Mirrored marks below are the byte case,
+    // because a client stores those bytes.
+    files: Object.fromEntries(
+      Object.entries(files)
+        .toSorted()
+        .map(([name, content]) => [name, digest(content)])
+    ),
+    // Mirrored brand marks are published next to the artifacts, never inside
+    // them: the digest and size let a consumer or the release check verify the
+    // bytes it fetched without trusting the release listing.
+    assets: iconAssets(index),
+  }
+  return { ...files, 'integrity.json': json(integrityBody) } as GeneratedArtifacts
+}
+
+export function iconAssets(index: ConsumerIndex): readonly PublishedAsset[] {
+  const assets = new Map<string, PublishedAsset>()
+  for (const product of Object.values(index.products)) {
+    if (!product.icon) continue
+    assets.set(product.icon.asset, publishedAssetOf(product.icon))
+  }
+  return [...assets.values()].toSorted((left, right) => left.name.localeCompare(right.name))
+}
+
+/**
+ * Publishes a verified artifact set to `generatedDirectory` under the output's
+ * coordination lock. See `catalog-store.ts` for the publication contract.
+ */
+export async function writeArtifacts(
+  generatedDirectory: string,
+  artifacts: GeneratedArtifacts,
+  options: PublishOptions = {}
+): Promise<void> {
+  await publishCatalog(generatedDirectory, artifacts as Record<string, string>, options)
+}
+
+function sortArtifactKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortArtifactKeys)
+  if (value !== null && typeof value === 'object')
+    return Object.fromEntries(
+      Object.keys(value as Record<string, unknown>)
+        .toSorted()
+        .map((key) => [key, sortArtifactKeys((value as Record<string, unknown>)[key])])
+    )
+  return value
+}
+
+function json(value: unknown): string {
+  return `${JSON.stringify(sortArtifactKeys(value), null, 2)}\n`
+}

package/src/build.ts

@@ -0,0 +1,131 @@
+import { mapWithConcurrency } from './concurrency.js'
+import { contentId } from './digest.js'
+import { normalizePlugin, type ReleaseOptions } from './plugin-release.js'
+import {
+  createSkippedPlugin,
+  PluginSafetyError,
+  UPSTREAM_WEATHER_SKIP_CODES,
+  type SkippedPlugin,
+} from './plugin-skips.js'
+import { assertRepositoryAllowed, DEFAULT_POLICY, type CatalogPolicy } from './policy.js'
+import {
+  CatalogSchema,
+  PluginSchema,
+  type Catalog,
+  type CatalogSource,
+  type Plugin,
+} from './schema.js'
+import type { ResolvedSource } from './source-resolution.js'
+import { canonicalRepositoryUrl } from './sources.js'
+import { orderLeadingPlugins } from './taxonomy.js'
+
+export interface BuildCatalogInput extends Omit<
+  ReleaseOptions,
+  'policy' | 'metadataOnly' | 'resolveExternalRefs'
+> {
+  readonly resolvedSources: readonly ResolvedSource[]
+  /** Each category's curated products, which head the catalog in this order. */
+  readonly leading?: Readonly<Record<string, readonly string[]>>
+  readonly policy?: CatalogPolicy
+  readonly metadataOnly?: boolean
+  readonly resolveExternalRefs?: boolean
+}
+
+interface BuildCatalogResult {
+  readonly catalog: Catalog
+  readonly skippedPlugins: readonly SkippedPlugin[]
+}
+
+export async function buildCatalog(input: BuildCatalogInput): Promise<Catalog> {
+  return (await buildCatalogInternal(input)).catalog
+}
+
+export async function buildCatalogInternal(input: BuildCatalogInput): Promise<BuildCatalogResult> {
+  const policy = input.policy ?? DEFAULT_POLICY
+  const options: ReleaseOptions = {
+    ...input,
+    policy,
+    metadataOnly: input.metadataOnly ?? false,
+    resolveExternalRefs: input.resolveExternalRefs ?? false,
+  }
+  for (const source of input.resolvedSources) {
+    assertRepositoryAllowed(source.config.repositoryUrl, policy)
+    for (const entry of source.parsed.entries) {
+      if (entry.source.kind === 'git') assertRepositoryAllowed(entry.source.repositoryUrl, policy)
+    }
+  }
+  const sourceRecords: CatalogSource[] = input.resolvedSources
+    .map(({ config, commitSha, retrievedAt, manifestDigest }) => ({
+      sourceId: config.sourceId,
+      displayName: config.displayName,
+      repositoryUrl: canonicalRepositoryUrl(config.repositoryUrl),
+      marketplaceDialect: config.marketplaceDialect,
+      manifestPath: config.manifestPath,
+      defaultBranch: config.defaultBranch,
+      resolvedCommitSha: commitSha,
+      retrievalTimestamp: retrievedAt,
+      trustClassification: config.trustClassification,
+      sourceManifestDigest: manifestDigest,
+      synchronizationStatus: 'synchronized' as const,
+    }))
+    .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId))
+  let plugins: Plugin[] = []
+  let skippedPlugins: SkippedPlugin[] = []
+  for (const source of input.resolvedSources) {
+    if (source.parsed.entries.length > policy.maxMarketplacePlugins)
+      throw new Error('MARKETPLACE_TOO_MANY_PLUGINS')
+    const normalized = await mapWithConcurrency(source.parsed.entries, 8, async (entry) => {
+      try {
+        const plugin = await normalizePlugin(source, entry, options)
+        try {
+          return { plugin: PluginSchema.parse(plugin) }
+        } catch {
+          throw new PluginSafetyError('PLUGIN_SCHEMA_INVALID', [])
+        }
+      } catch (error) {
+        const skipped = createSkippedPlugin(source, entry, error)
+        if (!skipped) throw error
+        return { skipped }
+      }
+    })
+    const sourcePlugins: Plugin[] = []
+    const sourceSkipped: SkippedPlugin[] = []
+    for (const result of normalized) {
+      if (result.plugin) sourcePlugins.push(result.plugin)
+      if (result.skipped) sourceSkipped.push(result.skipped)
+    }
+    const weatherSkips = sourceSkipped.filter((skipped) =>
+      UPSTREAM_WEATHER_SKIP_CODES.has(skipped.reasonCode)
+    )
+    if (source.parsed.entries.length > 0 && weatherSkips.length === source.parsed.entries.length)
+      throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [
+        canonicalRepositoryUrl(source.config.repositoryUrl),
+      ])
+    for (const plugin of sourcePlugins) plugins.push(plugin)
+    for (const skipped of sourceSkipped) skippedPlugins.push(skipped)
+  }
+  plugins = plugins.toSorted((left, right) => left.pluginId.localeCompare(right.pluginId))
+  skippedPlugins = skippedPlugins.toSorted(
+    (left, right) =>
+      left.pluginId.localeCompare(right.pluginId) ||
+      left.reasonCode.localeCompare(right.reasonCode) ||
+      left.paths.join('\0').localeCompare(right.paths.join('\0'))
+  )
+  const body = {
+    schemaVersion: 1 as const,
+    generatedAt:
+      sourceRecords
+        .map((s) => s.retrievalTimestamp)
+        .toSorted()
+        .at(-1) ?? new Date(0).toISOString(),
+    sources: sourceRecords,
+    plugins: orderLeadingPlugins({ plugins }, input.leading).plugins,
+  }
+  return {
+    catalog: CatalogSchema.parse({
+      ...body,
+      catalogId: contentId('catalog', body),
+    }),
+    skippedPlugins,
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,153 @@
+import { basename } from 'node:path'
+import { DEFAULT_POLICY, type CatalogPolicy } from './policy.js'
+import type { MarketplaceDialect } from './sources.js'
+import {
+  HarnessSchema,
+  type Capability,
+  type Harness,
+  type HarnessCompatibility,
+  type SecurityClassification,
+} from './schema.js'
+
+export function classifyCapabilities(
+  files: ReadonlyMap<string, Uint8Array>,
+  metadata?: Record<string, unknown>,
+  policy: CatalogPolicy = DEFAULT_POLICY
+): Capability[] {
+  const groups = new Map<string, string[]>()
+  const add = (type: Capability['type'], path: string) =>
+    groups.set(type, [...(groups.get(type) ?? []), path])
+  for (const path of files.keys()) {
+    const lower = path.toLocaleLowerCase()
+    const file = basename(lower)
+    if (file === 'skill.md' || lower.includes('/skills/')) add('skill', path)
+    if (file === '.mcp.json' || file === 'mcp.json' || lower.includes('/mcp-servers/'))
+      add('mcp-server', path)
+    if (lower.includes('/commands/') || lower.startsWith('commands/')) add('command', path)
+    if (lower.includes('/agents/') || lower.startsWith('agents/') || lower.includes('/subagents/'))
+      add('agent', path)
+    if (lower.includes('/hooks/') || lower.startsWith('hooks/') || file === 'hooks.json')
+      add('hook', path)
+    if (
+      lower.includes('/rules/') ||
+      lower.startsWith('rules/') ||
+      file === 'agents.md' ||
+      file === 'claude.md' ||
+      lower.includes('.cursor/rules/')
+    )
+      add('rule', path)
+    if (lower.includes('browser') || lower.includes('playwright') || lower.includes('chrome'))
+      add('browser', path)
+    if (lower.includes('/schedule') || lower.includes('/cron') || file.includes('schedule'))
+      add('scheduled-task', path)
+    if (lower.includes('/ui/') || lower.startsWith('ui/') || lower.includes('/components/'))
+      add('ui-component', path)
+    if (
+      lower.startsWith('bin/') ||
+      lower.startsWith('scripts/') ||
+      /\.(sh|bash|py|exe|bin)$/.test(file)
+    )
+      add('executable', path)
+  }
+  if (metadata && (metadata.mcpServers !== undefined || metadata.mcp !== undefined))
+    add('mcp-server', 'plugin-manifest')
+  if (metadata && (metadata.hooks !== undefined || metadata.hook !== undefined))
+    add('hook', 'plugin-manifest')
+  if (groups.size === 0) groups.set('unknown', ['plugin-root'])
+  return [...groups.entries()].map(([type, paths]) => ({
+    type: type as Capability['type'],
+    name: type,
+    paths: [...new Set(paths)].toSorted(),
+    metadata: {},
+    securityImpact: policy.sensitiveCapabilityTypes.includes(type) ? 'sensitive' : 'none',
+  }))
+}
+
+export function capabilitySummary(
+  capabilities: readonly Capability[]
+): Record<Capability['type'], number> {
+  const summary = {} as Record<Capability['type'], number>
+  for (const capability of capabilities) summary[capability.type] = capability.paths.length
+  return summary
+}
+
+export function createCompatibility(
+  dialect: MarketplaceDialect,
+  capabilities: readonly Capability[],
+  policy: CatalogPolicy = DEFAULT_POLICY
+): Record<Harness, HarnessCompatibility> {
+  const types = [...new Set(capabilities.map((capability) => capability.type))].toSorted()
+  const sensitive = types.filter((type) => policy.sensitiveCapabilityTypes.includes(type))
+  const make = (
+    status: HarnessCompatibility['status'],
+    reasons: string[]
+  ): HarnessCompatibility => ({
+    status,
+    reasons: [...new Set(reasons)].toSorted(),
+    responsibleCapabilities: types,
+  })
+  const result = {} as Record<Harness, HarnessCompatibility>
+  for (const harness of HarnessSchema.options) {
+    const native =
+      (harness === 'claude-code' && dialect === 'claude') ||
+      (harness === 'cursor' && dialect === 'cursor') ||
+      (harness === 'codex' && dialect === 'openai')
+    if (types.includes('executable'))
+      result[harness] = make('unsupported', [
+        'Executable components require harness-specific execution authority.',
+      ])
+    else if (types.includes('unknown'))
+      result[harness] = make('unknown', [
+        'The plugin content was not classified into a supported component type.',
+      ])
+    else if (native && sensitive.length === 0)
+      result[harness] = make('native', [
+        `The ${dialect} marketplace dialect matches the ${harness} harness.`,
+      ])
+    else if (sensitive.length > 0 && ['pi', 'hermes', 'opencode'].includes(harness))
+      result[harness] = make('partially-supported', [
+        `Sensitive capabilities require ${harness} policy and runtime review.`,
+        ...sensitive.map((type) => `Capability ${type} is not granted by this catalog.`),
+      ])
+    else if (
+      types.every((type) => ['skill', 'rule', 'mcp-server', 'command', 'agent'].includes(type))
+    )
+      result[harness] = make(
+        native ? 'native' : 'portable',
+        native
+          ? [`The ${dialect} marketplace dialect matches the ${harness} harness.`]
+          : ['Files can be copied or translated into the harness layout.']
+      )
+    else
+      result[harness] = make('requires-translation', [
+        'One or more capabilities need a harness-specific projection.',
+      ])
+  }
+  return result
+}
+
+export function createSecurity(
+  capabilities: readonly Capability[],
+  policy: CatalogPolicy,
+  metadataOnly: boolean
+): SecurityClassification {
+  const sensitive = [
+    ...new Set(
+      capabilities
+        .filter((capability) => policy.sensitiveCapabilityTypes.includes(capability.type))
+        .map((capability) => capability.type)
+    ),
+  ].toSorted()
+  const reasons =
+    sensitive.length > 0
+      ? sensitive.map((type) => `Contains ${type} capability metadata.`)
+      : metadataOnly
+        ? ['Content was not fetched in metadata-only mode.']
+        : ['No permission-sensitive executable capability was detected.']
+  return {
+    level: sensitive.length > 0 ? 'sensitive' : metadataOnly ? 'review' : 'low',
+    reasons,
+    permissionSensitiveChanges: sensitive,
+    contentResolution: metadataOnly ? 'metadata-only' : 'complete',
+  }
+}