@adea-ai/plugins 1.0.0

package/src/icons.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  iconAssetName,
+  iconOverrideFor,
+  inspectIconBytes,
+  MAX_ICON_BYTES,
+  parseProductIconOverrides,
+  selectIconPath,
+  sniffContentType,
+} from './icons.js'
+
+const PNG = new Uint8Array([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+])
+const JPEG = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46])
+const GIF = new Uint8Array([...'GIF89a'].map((character) => character.charCodeAt(0)))
+const WEBP = new Uint8Array([
+  ...'RIFF'.split('').map((c) => c.charCodeAt(0)),
+  0,
+  0,
+  0,
+  0,
+  ...'WEBP'.split('').map((c) => c.charCodeAt(0)),
+])
+const encode = (text: string): Uint8Array => new TextEncoder().encode(text)
+const CLEAN_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><rect width="8" height="8"/></svg>'
+
+describe('icon file selection', () => {
+  test('prefers the conventional mark in a conventional location', () => {
+    expect(selectIconPath(['assets/logo.png', 'assets/icon.svg'])).toBe('assets/icon.svg')
+    expect(selectIconPath(['assets/logo.png', 'docs/media/logo.png'])).toBe('assets/logo.png')
+    expect(selectIconPath(['images/logo.png', 'assets/logo.png'])).toBe('assets/logo.png')
+  })
+
+  test('prefers a scalable variant and the larger size of the same stem', () => {
+    expect(selectIconPath(['assets/icon.png', 'assets/icon.svg'])).toBe('assets/icon.svg')
+    expect(selectIconPath(['assets/icon-small.png', 'assets/icon-large.png'])).toBe(
+      'assets/icon-large.png'
+    )
+  })
+
+  test('accepts a vendor-named mark inside an asset directory', () => {
+    expect(selectIconPath(['codex-plugin/assets/atlan-logo.png'])).toBe(
+      'codex-plugin/assets/atlan-logo.png'
+    )
+    expect(selectIconPath(['assets/databricks.svg'])).toBe('assets/databricks.svg')
+  })
+
+  test('never mistakes documentation or repository infrastructure for a mark', () => {
+    expect(selectIconPath(['assets/screenshot-1.png', 'docs/preview.png'])).toBeNull()
+    expect(selectIconPath(['.github/img/cpu.svg'])).toBeNull()
+    expect(selectIconPath(['docs/architecture.svg'])).toBeNull()
+    expect(selectIconPath(['assets/banner.png'])).toBeNull()
+  })
+
+  test('ignores unsupported files and escapes, and is order independent', () => {
+    expect(selectIconPath(['assets/logo.txt', 'assets/logo.svg'])).toBe('assets/logo.svg')
+    expect(selectIconPath(['../assets/logo.svg'])).toBeNull()
+    expect(selectIconPath([])).toBeNull()
+    // An unnamed image at the plugin root is as likely a screenshot as a mark.
+    expect(selectIconPath(['screenshot.png', 'readme.md'])).toBeNull()
+    expect(selectIconPath(['assets/logo.png', 'assets/logo.svg'])).toBe(
+      selectIconPath(['assets/logo.svg', 'assets/logo.png'])
+    )
+  })
+
+  test('keeps a bare mark at the plugin root when it is named like a mark', () => {
+    expect(selectIconPath(['logo.svg'])).toBe('logo.svg')
+    expect(selectIconPath(['icon.png', 'readme.png'])).toBe('icon.png')
+  })
+})
+
+describe('icon byte inspection', () => {
+  test('sniffs supported raster types from magic bytes', () => {
+    expect(sniffContentType(PNG)).toBe('image/png')
+    expect(sniffContentType(JPEG)).toBe('image/jpeg')
+    expect(sniffContentType(GIF)).toBe('image/gif')
+    expect(sniffContentType(WEBP)).toBe('image/webp')
+    expect(sniffContentType(encode(`<?xml version="1.0"?>${CLEAN_SVG}`))).toBe('image/svg+xml')
+  })
+
+  test('accepts a clean mark and reports its content type', () => {
+    expect(inspectIconBytes(PNG)).toEqual({ contentType: 'image/png' })
+    expect(inspectIconBytes(encode(CLEAN_SVG))).toEqual({ contentType: 'image/svg+xml' })
+  })
+
+  test('accepts an exporter prologue and leading comments before the root element', () => {
+    const illustrator = `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 24.0.0, SVG Export Plug-In . SVG Version: 6.00 -->
+<!-- Second comment -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg"><rect width="8" height="8"/></svg>`
+    expect(sniffContentType(encode(illustrator))).toBe('image/svg+xml')
+    expect(inspectIconBytes(encode(illustrator))).toEqual({ contentType: 'image/svg+xml' })
+    // A document whose root element is not `<svg>` is still not an icon.
+    const html = `<!DOCTYPE html><html><body><svg></svg></body></html>`
+    expect(sniffContentType(encode(html))).toBeNull()
+    const declared = `<svg-not xmlns="http://www.w3.org/2000/svg"></svg-not>`
+    expect(sniffContentType(encode(declared))).toBeNull()
+  })
+
+  test('rejects empty, oversized and unsupported payloads', () => {
+    expect(inspectIconBytes(new Uint8Array())).toEqual({ rejected: 'EMPTY_FILE' })
+    expect(inspectIconBytes(new Uint8Array(MAX_ICON_BYTES + 1))).toEqual({
+      rejected: 'SIZE_LIMIT_EXCEEDED',
+    })
+    expect(inspectIconBytes(encode('#!/bin/sh\nrm -rf /'))).toEqual({
+      rejected: 'CONTENT_TYPE_UNSUPPORTED',
+    })
+  })
+
+  test('rejects SVG that could execute or reach the network', () => {
+    const cases = [
+      `<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>`,
+      `<svg xmlns="http://www.w3.org/2000/svg"><foreignObject/></svg>`,
+      `<svg xmlns="http://www.w3.org/2000/svg" onload="alert(1)"/>`,
+      `<svg xmlns="http://www.w3.org/2000/svg"><image href="https://evil.example/x.png"/></svg>`,
+      `<svg xmlns="http://www.w3.org/2000/svg"><a xlink:href="//evil.example">x</a></svg>`,
+      `<svg xmlns="http://www.w3.org/2000/svg"><use href="//evil.example#x"/></svg>`,
+      `<!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]><svg>&xxe;</svg>`,
+    ]
+    for (const source of cases)
+      expect(inspectIconBytes(encode(source)), source.slice(0, 40)).toEqual({
+        rejected: expect.stringMatching(/^SVG_(ACTIVE_CONTENT|EXTERNAL_REFERENCE)$/) as never,
+      })
+  })
+})
+
+describe('icon asset names', () => {
+  test('is content addressed and keeps a usable extension', () => {
+    const name = iconAssetName(`sha256:${'a'.repeat(64)}`, 'image/png')
+    expect(name).toBe(`icon-${'a'.repeat(32)}.png`)
+    expect(iconAssetName(`sha256:${'b'.repeat(64)}`, 'image/svg+xml')).toBe(
+      `icon-${'b'.repeat(32)}.svg`
+    )
+    // Identical bytes always resolve to the same asset, so caches stay warm.
+    expect(iconAssetName(`sha256:${'c'.repeat(64)}`, 'image/webp')).toBe(
+      iconAssetName(`sha256:${'c'.repeat(64)}`, 'image/webp')
+    )
+  })
+
+  test('refuses a content type it cannot name', () => {
+    expect(() => iconAssetName(`sha256:${'d'.repeat(64)}`, 'text/html' as never)).toThrow(
+      'ICON_CONTENT_TYPE_UNSUPPORTED'
+    )
+  })
+})
+
+describe('brand mark overrides', () => {
+  test('accepts a forced path, an explicit opt-out and a vendor site', () => {
+    const parsed = parseProductIconOverrides({
+      schemaVersion: 1,
+      overrides: {
+        github: 'assets/logo.svg',
+        legacy: null,
+        servicenow: 'https://www.servicenow.com/',
+      },
+    })
+    expect(iconOverrideFor(parsed, 'github')).toEqual({ forced: 'assets/logo.svg' })
+    expect(iconOverrideFor(parsed, 'legacy')).toEqual({ forced: null })
+    expect(iconOverrideFor(parsed, 'servicenow')).toEqual({ site: 'https://www.servicenow.com/' })
+    expect(iconOverrideFor(parsed, 'unlisted')).toBeUndefined()
+    expect(iconOverrideFor(undefined, 'github')).toBeUndefined()
+  })
+
+  test('rejects malformed configuration', () => {
+    expect(() => parseProductIconOverrides(null)).toThrow('PRODUCT_ICONS_INVALID')
+    expect(() => parseProductIconOverrides({ schemaVersion: 2, overrides: {} })).toThrow(
+      'PRODUCT_ICONS_INVALID'
+    )
+    expect(() => parseProductIconOverrides({ schemaVersion: 1 })).toThrow('PRODUCT_ICONS_INVALID')
+    expect(() =>
+      parseProductIconOverrides({ schemaVersion: 1, overrides: { Github: null } })
+    ).toThrow('PRODUCT_ICONS_KEY_INVALID')
+    expect(() =>
+      parseProductIconOverrides({ schemaVersion: 1, overrides: { github: '/etc/passwd' } })
+    ).toThrow('PRODUCT_ICONS_PATH_INVALID')
+    expect(() =>
+      parseProductIconOverrides({ schemaVersion: 1, overrides: { github: '../../secret.png' } })
+    ).toThrow('PRODUCT_ICONS_PATH_INVALID')
+    expect(() =>
+      parseProductIconOverrides({ schemaVersion: 1, overrides: { github: 'https://localhost/' } })
+    ).toThrow('PRODUCT_ICONS_SITE_UNSUPPORTED')
+  })
+})

package/src/icons.ts

@@ -0,0 +1,297 @@
+/**
+ * Compile-time icon resolution.
+ *
+ * Marketplaces do not declare an icon field, so a plugin's mark is a file in
+ * its own content (`assets/logo.svg`, `assets/icon-large.png`, ...). Resolving
+ * one at compile time removes a runtime guess from consumers, and mirroring the
+ * bytes at publish time removes the upstream fetch entirely.
+ */
+
+/** Why a candidate file was rejected as an icon. */
+export type IconRejection =
+  | 'CONTENT_TYPE_UNSUPPORTED'
+  | 'EMPTY_FILE'
+  | 'SIZE_LIMIT_EXCEEDED'
+  | 'SVG_ACTIVE_CONTENT'
+  | 'SVG_EXTERNAL_REFERENCE'
+
+/** Content types the catalog will publish as a brand mark. */
+export type IconContentType =
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/gif'
+  | 'image/webp'
+  | 'image/svg+xml'
+  | 'image/x-icon'
+
+/** Icon file size ceiling; a brand mark is never a large asset. */
+export const MAX_ICON_BYTES = 1024 * 1024
+
+const SUPPORTED_EXTENSIONS = ['svg', 'png', 'webp', 'jpg', 'jpeg', 'gif', 'ico'] as const
+
+/** Ranked basenames; earlier entries win. Variants sort by the rank of the stem. */
+const STEM_RANK: Readonly<Record<string, number>> = {
+  icon: 0,
+  appicon: 0,
+  'app-icon': 0,
+  avatar: 2,
+  logo: 3,
+  mark: 4,
+  brand: 4,
+}
+const EXTENSION_RANK: Readonly<Record<string, number>> = {
+  svg: 0,
+  png: 1,
+  webp: 2,
+  ico: 3,
+  jpg: 4,
+  jpeg: 5,
+  gif: 6,
+}
+/** Preferred containers, best first. Files outside these are considered last. */
+const DIRECTORY_RANK: Readonly<Record<string, number>> = {
+  assets: 0,
+  '.assets': 1,
+  img: 2,
+  images: 3,
+  media: 4,
+  static: 5,
+}
+/** Files that are documentation, screenshots or brand collateral, not marks. */
+const EXCLUDED =
+  /(screenshot|screen-shot|preview|example|sample|demo|mockup|diagram|architecture|flowchart|flow-|banner|hero|cover|thumbnail|chart|graph|illustration|photo)/
+/** Repository infrastructure: CI images and templates, never a product mark. */
+const EXCLUDED_DIRECTORIES = ['.github', '.gitlab']
+
+const MARK_WORDS = new Set([
+  'icon',
+  'appicon',
+  'avatar',
+  'logo',
+  'mark',
+  'brand',
+  'logomark',
+  'wordmark',
+])
+const VARIANT_WORDS = new Set([
+  'large',
+  'small',
+  'light',
+  'dark',
+  'mono',
+  'white',
+  'black',
+  'positive',
+  'negative',
+  'color',
+  'colour',
+  'primary',
+  'secondary',
+  'horizontal',
+  'vertical',
+  'square',
+  'flat',
+  'glyph',
+])
+
+/**
+ * Splits a file name into mark tokens. Separators are normalised because
+ * vendors write marks as `logo.svg`, `atlan-logo.png`, `Dynatrace_Logo_color_positive.png`
+ * or `cs logo big.png` alike.
+ */
+function splitName(basename: string): { stems: string[]; marks: boolean; size: number } {
+  const withoutExtension = basename.slice(0, basename.lastIndexOf('.'))
+  const words = withoutExtension
+    .split(/[\s._-]+/)
+    .filter(Boolean)
+    .map((word) => word.toLowerCase())
+  const size = words.some((word) => word === 'small') ? 1 : 0
+  const marks = words.some((word) => MARK_WORDS.has(word))
+  const stems = words.filter((word) => !MARK_WORDS.has(word) && !VARIANT_WORDS.has(word))
+  return { stems, marks, size }
+}
+
+/**
+ * Chooses one icon file from a release's file index, deterministically.
+ *
+ * Preference: `assets/icon.svg` before `assets/icon.png` before `assets/logo.*`,
+ * an `icon`/`logo` stem before `avatar`/`mark`/`brand`, an `assets` directory
+ * before other asset directories, SVG before raster for the same stem, and a
+ * `-large` variant before `-small`. Anything that looks like documentation or a
+ * screenshot is never selected. Ties break on path so the result is stable.
+ */
+export function selectIconPath(fileIndex: readonly string[]): string | null {
+  let best: { path: string; score: readonly number[] } | null = null
+  for (const raw of fileIndex) {
+    const path = raw.replace(/^\.?\//, '')
+    if (path.includes('..')) continue
+    const segments = path.split('/')
+    const basename = segments.pop() ?? ''
+    const extension = basename.slice(basename.lastIndexOf('.') + 1).toLowerCase()
+    if (!(SUPPORTED_EXTENSIONS as readonly string[]).includes(extension)) continue
+    if (EXCLUDED.test(basename)) continue
+    const directories = segments.map((segment) => segment.toLowerCase())
+    if (directories.some((segment) => EXCLUDED.test(segment))) continue
+    if (directories.some((segment) => EXCLUDED_DIRECTORIES.includes(segment))) continue
+    const { stems, marks, size } = splitName(basename)
+    const single = stems.length === 1 ? stems[0]! : undefined
+    const stemRank = marks ? (single ? (STEM_RANK[single] ?? 0) : 0) : undefined
+    const nested = directories.filter((segment) => DIRECTORY_RANK[segment] !== undefined)
+    // A mark named as one — `logo.svg`, `atlan-logo.png`, `cs_logo_large.png` —
+    // is accepted anywhere, including the plugin root. An unnamed image must sit
+    // in a known asset directory, because a bare `banner.png` at the root is as
+    // likely to be documentation as a brand mark.
+    const directoryRank =
+      nested.length > 0
+        ? (DIRECTORY_RANK[nested[nested.length - 1]!] ?? 0)
+        : stemRank === undefined
+          ? Number.POSITIVE_INFINITY
+          : 0
+    if (!Number.isFinite(directoryRank)) continue
+    const score = [stemRank ?? 5, directoryRank, size, EXTENSION_RANK[extension] ?? 9, path.length]
+    if (!best || compareScore(score, best.score) < 0) best = { path, score }
+  }
+  return best ? best.path : null
+}
+
+function compareScore(left: readonly number[], right: readonly number[]): number {
+  for (let index = 0; index < left.length; index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0)
+    if (difference !== 0) return difference
+  }
+  return 0
+}
+
+const SVG_ACTIVE_CONTENT =
+  /<\s*script|<\s*foreignObject|<\s*iframe|<\s*use[^>]+href\s*=\s*["']?\s*(?:https?:)?\/\/|javascript:|<!ENTITY|<!DOCTYPE[^>]+\[|on(?:load|error|click|mouseover|focus|begin)\s*=/i
+const SVG_EXTERNAL_REFERENCE = /(?:href|xlink:href|src|data|poster)\s*=\s*["']?\s*(?:https?:)?\/\//i
+
+/** Sniffs a supported image type from magic bytes; SVG is detected as text. */
+export function sniffContentType(bytes: Uint8Array): IconContentType | null {
+  const ascii = (offset: number, length: number): string =>
+    String.fromCharCode(...bytes.subarray(offset, offset + length))
+  if (bytes.length >= 8 && ascii(0, 8) === '\x89PNG\r\n\x1a\n') return 'image/png'
+  if (bytes.length >= 3 && ascii(0, 3) === '\xff\xd8\xff') return 'image/jpeg'
+  if (bytes.length >= 6 && ascii(0, 4) === 'GIF8') return 'image/gif'
+  if (bytes.length >= 12 && ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') return 'image/webp'
+  // Icon container: reserved(2), type 1 (icon) or 2 (cursor), count >= 1.
+  if (
+    bytes.length >= 6 &&
+    bytes[0] === 0 &&
+    bytes[1] === 0 &&
+    (bytes[2] === 1 || bytes[2] === 2) &&
+    bytes[3] === 0 &&
+    ((bytes[4] ?? 0) | ((bytes[5] ?? 0) << 8)) > 0
+  )
+    return 'image/x-icon'
+  if (bytes.length > 0) {
+    // An XML prologue, a doctype and leading comments may all precede the root
+    // element: exporters such as Adobe Illustrator and Figma emit them. What
+    // matters is that the document's root element is `<svg>`, not `<html>`.
+    const head = new TextDecoder()
+      .decode(bytes.subarray(0, Math.min(bytes.length, 4096)))
+      .trimStart()
+      .replace(/^<\?xml[\s\S]*?\?>/i, '')
+      .replace(/^<!DOCTYPE[^>]*?(?:\[[\s\S]*?\])?>/i, '')
+      .replace(/^(?:\s*<!--[\s\S]*?-->)+/, '')
+      .trimStart()
+    if (/^<svg[\s>]/i.test(head)) return 'image/svg+xml'
+  }
+  return null
+}
+
+/**
+ * Verifies icon bytes before they are published.
+ *
+ * SVG is text that a browser can execute when it is inlined, so active content
+ * and external references are rejected outright. Consumers must still render a
+ * mirrored SVG through an `<img>` element and never inline it into the DOM.
+ */
+export function inspectIconBytes(
+  bytes: Uint8Array
+): { contentType: IconContentType } | { rejected: IconRejection } {
+  if (bytes.length === 0) return { rejected: 'EMPTY_FILE' }
+  if (bytes.length > MAX_ICON_BYTES) return { rejected: 'SIZE_LIMIT_EXCEEDED' }
+  const contentType = sniffContentType(bytes)
+  if (!contentType) return { rejected: 'CONTENT_TYPE_UNSUPPORTED' }
+  if (contentType === 'image/svg+xml') {
+    const text = new TextDecoder().decode(bytes)
+    if (SVG_ACTIVE_CONTENT.test(text)) return { rejected: 'SVG_ACTIVE_CONTENT' }
+    if (SVG_EXTERNAL_REFERENCE.test(text)) return { rejected: 'SVG_EXTERNAL_REFERENCE' }
+  }
+  return { contentType }
+}
+
+const EXTENSION_BY_CONTENT_TYPE: Readonly<Record<IconContentType, string>> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+  'image/x-icon': 'ico',
+}
+
+/**
+ * Content-addressed asset name. Release assets cannot contain `/`, so the
+ * digest prefix and extension form one flat name that any release can host.
+ */
+export function iconAssetName(digest: string, contentType: IconContentType): string {
+  const extension = EXTENSION_BY_CONTENT_TYPE[contentType]
+  if (!extension) throw new Error(`ICON_CONTENT_TYPE_UNSUPPORTED: ${contentType}`)
+  const hex = digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest
+  return `icon-${hex.slice(0, 32)}.${extension}`
+}
+
+/**
+ * Curation override for a product's brand mark, keyed by product key.
+ *
+ * `null` publishes no mark; a path forces a file inside the plugin content; an
+ * `https://` value names the vendor site to take the mark from. The override
+ * exists because the selection rule is a heuristic over vendor filenames: many
+ * products ship no conventional mark and declare nothing but a repository, and
+ * a curator may know the real brand source.
+ */
+export interface ProductIconOverrides {
+  readonly schemaVersion: 1
+  readonly overrides: Readonly<Record<string, string | null>>
+}
+
+export function parseProductIconOverrides(input: unknown): ProductIconOverrides {
+  if (typeof input !== 'object' || input === null) throw new Error('PRODUCT_ICONS_INVALID')
+  const raw = input as Partial<ProductIconOverrides>
+  if (raw.schemaVersion !== 1) throw new Error('PRODUCT_ICONS_INVALID')
+  const overrides = raw.overrides
+  if (typeof overrides !== 'object' || overrides === null) throw new Error('PRODUCT_ICONS_INVALID')
+  for (const [productKey, value] of Object.entries(overrides)) {
+    if (!/^[a-z0-9][a-z0-9-]{1,127}$/.test(productKey))
+      throw new Error(`PRODUCT_ICONS_KEY_INVALID: ${productKey}`)
+    if (value === null) continue
+    if (typeof value !== 'string' || value.length === 0 || value.length > 1024)
+      throw new Error(`PRODUCT_ICONS_PATH_INVALID: ${productKey}`)
+    if (value.startsWith('https://')) {
+      // Only the shape is checked here; site-icons applies the full host policy
+      // when it resolves the mark, so a bad host simply yields no icon.
+      if (!/^https:\/\/[a-z0-9.-]+\.[a-z]{2,}/i.test(value))
+        throw new Error(`PRODUCT_ICONS_SITE_UNSUPPORTED: ${productKey}`)
+      continue
+    }
+    if (value.startsWith('/') || value.includes('..'))
+      throw new Error(`PRODUCT_ICONS_PATH_INVALID: ${productKey}`)
+  }
+  return { schemaVersion: 1, overrides: { ...overrides } }
+}
+
+/**
+ * Reads the override for a product: `forced` names a content path or `null` to
+ * publish no mark, and `site` names a vendor site to take the mark from.
+ */
+export function iconOverrideFor(
+  overrides: ProductIconOverrides | undefined,
+  productKey: string
+): { readonly forced?: string | null; readonly site?: string } | undefined {
+  if (!overrides || !(productKey in overrides.overrides)) return undefined
+  const value = overrides.overrides[productKey]
+  if (value === null) return { forced: null }
+  if (typeof value !== 'string') return undefined
+  return value.startsWith('https://') ? { site: value } : { forced: value }
+}