@adea-ai/plugins 1.0.0

package/src/site-icons.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  discoverSiteIcons,
+  isPublicHostname,
+  isVendorHomepage,
+  resolveSiteIcon,
+  type SiteIconFetcher,
+} from './site-icons.js'
+import { byteDigest } from './index.js'
+
+const PNG = new Uint8Array([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+])
+const ICO = new Uint8Array([0, 0, 1, 0, 1, 0, 16, 16, 0, 0, 1, 0, 32, 0])
+const SVG = new TextEncoder().encode(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><rect width="8" height="8"/></svg>'
+)
+const SCRIPTED_SVG = new TextEncoder().encode(
+  '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>'
+)
+
+function toBytes(value: string | Uint8Array): Uint8Array {
+  return typeof value === 'string' ? new TextEncoder().encode(value) : value
+}
+
+function fetcher(site: Record<string, string | Uint8Array>): SiteIconFetcher & {
+  textCalls: string[]
+  byteCalls: string[]
+} {
+  const textCalls: string[] = []
+  const byteCalls: string[] = []
+  return {
+    textCalls,
+    byteCalls,
+    digest: (bytes) => byteDigest(bytes),
+    fetchText: async (url) => {
+      textCalls.push(url)
+      const value = site[url]
+      if (value === undefined) throw new Error('ENOENT')
+      return typeof value === 'string' ? value : new TextDecoder().decode(value)
+    },
+    fetchBytes: async (url) => {
+      byteCalls.push(url)
+      const value = site[url]
+      if (value === undefined) throw new Error('ENOENT')
+      return toBytes(value)
+    },
+  }
+}
+
+describe('vendor homepage eligibility', () => {
+  test('accepts a vendor site and rejects repository and non-public hosts', () => {
+    expect(isVendorHomepage('https://appwrite.io/')).toBe(true)
+    expect(isVendorHomepage('https://docs.voxel51.com/')).toBe(true)
+    expect(isVendorHomepage('https://github.com/foo/bar')).toBe(false)
+    expect(isVendorHomepage('https://raw.githubusercontent.com/foo/bar')).toBe(false)
+    expect(isVendorHomepage('https://gitlab.com/foo/bar')).toBe(false)
+    expect(isVendorHomepage('http://appwrite.io/')).toBe(false)
+    expect(isVendorHomepage('http://localhost:8080/')).toBe(false)
+    expect(isVendorHomepage('https://127.0.0.1/')).toBe(false)
+    expect(isVendorHomepage('https://10.0.0.5/')).toBe(false)
+    expect(isVendorHomepage('https://169.254.169.254/latest/meta-data')).toBe(false)
+    expect(isVendorHomepage('https://192.168.1.10/')).toBe(false)
+    expect(isVendorHomepage('https://service.internal/')).toBe(false)
+    expect(isVendorHomepage('not a url')).toBe(false)
+    expect(isVendorHomepage(undefined)).toBe(false)
+  })
+
+  test('classifies hostnames', () => {
+    expect(isPublicHostname('example.com')).toBe(true)
+    expect(isPublicHostname('bare-hostname')).toBe(false)
+    expect(isPublicHostname('::1')).toBe(false)
+    expect(isPublicHostname('fd00::1')).toBe(false)
+  })
+})
+
+describe('site icon discovery', () => {
+  const html = `<!doctype html><html><head>
+    <link rel="icon" href="/favicon.ico">
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon.png">
+    <link rel="stylesheet" href="/app.css">
+    <link rel="mask-icon" href="/mask.svg">
+    <link rel="icon" type="image/svg+xml" href="https://cdn.example.com/icon.svg">
+  </head><body><img src="/hero.png"></body></html>`
+
+  test('ranks apple-touch-icon first and resolves relative URLs', () => {
+    expect(discoverSiteIcons(html, 'https://vendor.example/')).toEqual([
+      'https://vendor.example/apple-icon.png',
+      'https://vendor.example/favicon.ico',
+      'https://cdn.example.com/icon.svg',
+      'https://vendor.example/mask.svg',
+    ])
+  })
+
+  test('prefers the larger declared size within a group', () => {
+    const sizes = `<link rel="icon" sizes="32x32" href="/small.png">
+      <link rel="icon" sizes="512x512" href="/large.png">`
+    expect(discoverSiteIcons(sizes, 'https://vendor.example/')[0]).toBe(
+      'https://vendor.example/large.png'
+    )
+  })
+
+  test('falls back to /favicon.ico and refuses unsafe candidates', () => {
+    expect(discoverSiteIcons('<html><head></head></html>', 'https://vendor.example/page')).toEqual([
+      'https://vendor.example/favicon.ico',
+    ])
+    expect(
+      discoverSiteIcons(
+        '<link rel="icon" href="http://vendor.example/icon.png">',
+        'https://vendor.example/'
+      )
+    ).toEqual(['https://vendor.example/favicon.ico'])
+    expect(
+      discoverSiteIcons('<link rel="icon" href="http://localhost/icon.png">', 'https://v.example/')
+    ).toEqual(['https://v.example/favicon.ico'])
+  })
+})
+
+describe('site icon resolution', () => {
+  const homepage = 'https://vendor.example/'
+  const html = '<head><link rel="apple-touch-icon" href="/apple-icon.png"></head>'
+
+  test('returns the first usable icon with provenance', async () => {
+    const io = fetcher({ [homepage]: html, 'https://vendor.example/apple-icon.png': PNG })
+    const result = await resolveSiteIcon(homepage, io)
+    expect('contentType' in result && result).toMatchObject({
+      url: 'https://vendor.example/apple-icon.png',
+      homepage,
+      contentType: 'image/png',
+      digest: byteDigest(PNG),
+    })
+    expect(io.byteCalls).toEqual(['https://vendor.example/apple-icon.png'])
+  })
+
+  test('accepts an icon container and skips a candidate that fails inspection', async () => {
+    const ico = fetcher({ [homepage]: html, 'https://vendor.example/apple-icon.png': ICO })
+    expect(await resolveSiteIcon(homepage, ico)).toMatchObject({ contentType: 'image/x-icon' })
+
+    const scripted = fetcher({
+      [homepage]: html,
+      'https://vendor.example/apple-icon.png': SCRIPTED_SVG,
+      'https://vendor.example/favicon.ico': SVG,
+    })
+    expect(await resolveSiteIcon(homepage, scripted)).toMatchObject({
+      url: 'https://vendor.example/favicon.ico',
+      contentType: 'image/svg+xml',
+    })
+  })
+
+  test('reports a reason instead of throwing', async () => {
+    const missing = fetcher({})
+    expect(await resolveSiteIcon(homepage, missing)).toMatchObject({
+      failed: expect.stringContaining('HOMEPAGE_FETCH_FAILED') as never,
+    })
+    const noIcon = fetcher({ [homepage]: '<head></head>' })
+    expect(await resolveSiteIcon(homepage, noIcon)).toEqual({ failed: 'NO_USABLE_ICON' })
+    expect(await resolveSiteIcon('https://github.com/foo/bar', fetcher({}))).toEqual({
+      failed: 'NOT_VENDOR_HOMEPAGE',
+    })
+  })
+
+  test('parses only the document head of a large landing page', async () => {
+    const huge = `${html}${'x'.repeat(600 * 1024)}`
+    const io = fetcher({ [homepage]: huge, 'https://vendor.example/apple-icon.png': PNG })
+    const result = await resolveSiteIcon(homepage, io)
+    expect('contentType' in result).toBe(true)
+
+    const oversized = fetcher({ [homepage]: 'x'.repeat(5 * 1024 * 1024) })
+    expect(await resolveSiteIcon(homepage, oversized)).toEqual({ failed: 'HOMEPAGE_TOO_LARGE' })
+  })
+})

package/src/site-icons.ts

@@ -0,0 +1,161 @@
+import { inspectIconBytes, MAX_ICON_BYTES, type IconContentType } from './icons.js'
+
+/**
+ * Site icon discovery, for products that ship no brand mark of their own.
+ *
+ * Many plugins are a thin wrapper over a vendor's API: the content carries no
+ * logo, and the declared homepage is the only pointer to the vendor. Fetching
+ * that site's icon once at publish time, verifying it and mirroring it as a
+ * release asset replaces a per-render favicon lookup in the client.
+ */
+export const SITE_ICON_MAX_HTML_BYTES = 4 * 1024 * 1024
+
+/**
+ * Only the document head is parsed. Icon links are declared there, and vendor
+ * landing pages are frequently several megabytes of markup and script.
+ */
+export const SITE_ICON_HEAD_BYTES = 256 * 1024
+
+/** Hosts that serve repository chrome rather than a product brand. */
+const REPOSITORY_HOSTS =
+  /(^|\.)(github\.com|githubusercontent\.com|gitlab\.com|bitbucket\.org|codeberg\.org|sourceforge\.net|gitee\.com)$/
+
+export interface SiteIcon {
+  readonly url: string
+  /** The product homepage the icon was discovered from. */
+  readonly homepage: string
+  readonly bytes: Uint8Array
+  readonly contentType: IconContentType
+  readonly digest: string
+}
+
+/**
+ * Whether a homepage can stand in for a product brand.
+ *
+ * Only HTTPS sites qualify: a repository URL would yield the forge's own logo,
+ * and a non-routable host is a request forgery risk rather than a vendor site.
+ */
+export function isVendorHomepage(homepage: string | undefined): boolean {
+  if (!homepage) return false
+  let parsed: URL
+  try {
+    parsed = new URL(homepage)
+  } catch {
+    return false
+  }
+  if (parsed.protocol !== 'https:') return false
+  return isPublicHostname(parsed.hostname) && !REPOSITORY_HOSTS.test(parsed.hostname)
+}
+
+/** Rejects loopback, link-local, private and internal hostnames. */
+export function isPublicHostname(hostname: string): boolean {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local')) return false
+  if (host.endsWith('.internal') || host.endsWith('.home.arpa')) return false
+  if (host === '::1' || host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd'))
+    return false
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+  if (ipv4) {
+    const [a, b] = ipv4.slice(1).map(Number) as [number, number]
+    if (a === 0 || a === 10 || a === 127 || a >= 224) return false
+    if (a === 169 && b === 254) return false
+    if (a === 172 && b >= 16 && b <= 31) return false
+    if (a === 192 && b === 168) return false
+    return true
+  }
+  // A bare hostname label has no public site behind it.
+  return host.includes('.')
+}
+
+/**
+ * Extracts icon URLs from a document head, best candidate first.
+ *
+ * `apple-touch-icon` is preferred because it is a square PNG sized for a home
+ * screen; declared `icon` links follow in declared order; `/favicon.ico` is the
+ * conventional last resort when nothing is declared.
+ */
+export function discoverSiteIcons(html: string, baseUrl: string): readonly string[] {
+  const candidates: { href: string; rank: number }[] = []
+  const linkTags = html.match(/<link\b[^>]*>/gi) ?? []
+  for (const tag of linkTags) {
+    const rel = /\brel\s*=\s*["']?([^"'>]+)/i.exec(tag)?.[1]?.toLowerCase() ?? ''
+    if (!/\b(apple-touch-icon|icon|shortcut|mask-icon)\b/.test(rel)) continue
+    const href = /\bhref\s*=\s*["']([^"']+)["']/i.exec(tag)?.[1]
+    if (!href) continue
+    const sizes = /\bsizes\s*=\s*["']?([0-9]+x[0-9]+)/i.exec(tag)?.[1]
+    const edge = sizes ? Number.parseInt(sizes, 10) : 180
+    // Apple touch icons lead; larger declared sizes lead within a group.
+    const rank = rel.includes('apple-touch-icon') ? 0 : rel.includes('mask-icon') ? 2 : 1
+    candidates.push({ href, rank: rank * 1000 + Math.max(0, 512 - (edge || 180)) })
+  }
+  const resolved: { url: string; rank: number }[] = []
+  for (const candidate of candidates.toSorted((left, right) => left.rank - right.rank)) {
+    try {
+      const url = new URL(candidate.href, baseUrl)
+      if (url.protocol !== 'https:' || !isPublicHostname(url.hostname)) continue
+      resolved.push({ url: url.toString(), rank: candidate.rank })
+    } catch {
+      continue
+    }
+  }
+  // The conventional location is always the last candidate: a site whose
+  // declared icon turns out to be unusable can still resolve through it.
+  try {
+    const fallback = new URL('/favicon.ico', baseUrl)
+    if (fallback.protocol === 'https:' && isPublicHostname(fallback.hostname))
+      resolved.push({ url: fallback.toString(), rank: 5000 })
+  } catch {
+    // An unparseable base leaves the declared candidates only.
+  }
+  return [...new Set(resolved.toSorted((l, r) => l.rank - r.rank).map((item) => item.url))]
+}
+
+export interface SiteIconFetcher {
+  readonly fetchText: (url: string) => Promise<string>
+  readonly fetchBytes: (url: string) => Promise<Uint8Array>
+  readonly digest: (bytes: Uint8Array) => string
+}
+
+/**
+ * Resolves the best usable icon for a vendor homepage.
+ *
+ * Every candidate is inspected with the same gate as an in-content mark, so a
+ * site that serves an oversized, unsupported or scripted image yields no icon
+ * rather than a mirrored liability.
+ */
+export async function resolveSiteIcon(
+  homepage: string,
+  fetcher: SiteIconFetcher
+): Promise<SiteIcon | { readonly failed: string }> {
+  if (!isVendorHomepage(homepage)) return { failed: 'NOT_VENDOR_HOMEPAGE' }
+  let html: string
+  try {
+    html = await fetcher.fetchText(homepage)
+  } catch (error) {
+    return { failed: `HOMEPAGE_FETCH_FAILED: ${message(error)}` }
+  }
+  if (html.length > SITE_ICON_MAX_HTML_BYTES) return { failed: 'HOMEPAGE_TOO_LARGE' }
+  for (const url of discoverSiteIcons(html.slice(0, SITE_ICON_HEAD_BYTES), homepage)) {
+    let bytes: Uint8Array
+    try {
+      bytes = await fetcher.fetchBytes(url)
+    } catch {
+      continue
+    }
+    if (bytes.byteLength > MAX_ICON_BYTES) continue
+    const inspected = inspectIconBytes(bytes)
+    if (!('contentType' in inspected)) continue
+    return {
+      url,
+      homepage,
+      bytes,
+      contentType: inspected.contentType,
+      digest: fetcher.digest(bytes),
+    }
+  }
+  return { failed: 'NO_USABLE_ICON' }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/sources.ts

@@ -0,0 +1,360 @@
+import { createHash } from 'node:crypto'
+
+export type MarketplaceDialect = 'openai' | 'cursor' | 'claude'
+
+export interface SourceConfig {
+  readonly sourceId: string
+  readonly displayName: string
+  readonly repositoryUrl: string
+  readonly marketplaceDialect: MarketplaceDialect
+  readonly manifestPath: string
+  readonly defaultBranch: string
+  readonly trustClassification: 'official'
+  readonly fixturePath?: string
+  readonly fixtureCommitSha?: string
+}
+
+export type PluginSourceSpec =
+  | { readonly kind: 'local'; readonly path: string }
+  | {
+      readonly kind: 'git'
+      readonly repositoryUrl: string
+      readonly subdirectory: string
+      readonly ref?: string
+      readonly sha?: string
+    }
+
+export interface MarketplacePluginEntry {
+  readonly name: string
+  readonly displayName?: string | undefined
+  readonly description: string
+  readonly categories: readonly string[]
+  readonly keywords: readonly string[]
+  readonly authors: readonly string[]
+  readonly homepage?: string | undefined
+  readonly icons: readonly string[]
+  readonly source: PluginSourceSpec
+  readonly policy: Record<string, unknown>
+  readonly raw: Record<string, unknown>
+  readonly entryDigest: string
+}
+
+export interface ParsedMarketplace {
+  readonly marketplaceName: string
+  readonly marketplaceDescription: string
+  readonly owner: readonly string[]
+  readonly entries: readonly MarketplacePluginEntry[]
+  readonly raw: Record<string, unknown>
+}
+
+export class SourceAdapterError extends Error {
+  constructor(
+    readonly code: string,
+    readonly details: readonly string[] = []
+  ) {
+    super(`${code}${details.length > 0 ? `: ${details.join(', ')}` : ''}`)
+    this.name = 'SourceAdapterError'
+  }
+}
+
+export function parseMarketplaceManifest(input: unknown, source: SourceConfig): ParsedMarketplace {
+  const root = record(input, 'MARKETPLACE_NOT_OBJECT')
+  const plugins = root.plugins
+  if (!Array.isArray(plugins)) throw new SourceAdapterError('MARKETPLACE_PLUGINS_REQUIRED')
+
+  const entries = plugins.map((value, index) => parsePluginEntry(value, source, index))
+  const duplicateNames = new Set<string>()
+  for (const entry of entries) {
+    if (duplicateNames.has(entry.name))
+      throw new SourceAdapterError('DUPLICATE_PLUGIN_NAME', [entry.name])
+    duplicateNames.add(entry.name)
+  }
+  return {
+    marketplaceName: stringValue(root.name) ?? source.displayName,
+    marketplaceDescription: stringValue(root.description) ?? '',
+    owner: ownerNames(root.owner),
+    entries,
+    raw: root,
+  }
+}
+
+/** Parse JSON while rejecting duplicate object keys instead of accepting last-key-wins input. */
+export function parseJsonDocument(text: string): unknown {
+  let index = 0
+  const skip = () => {
+    while (/\s/.test(text[index] ?? '')) index += 1
+  }
+  const string = (): string => {
+    const start = index
+    if (text[index] !== '"') throw new SourceAdapterError('JSON_MALFORMED')
+    index += 1
+    while (index < text.length) {
+      const character = text[index]
+      if (character === '\\') {
+        index += 2
+        continue
+      }
+      if (character === '"') {
+        index += 1
+        try {
+          return JSON.parse(text.slice(start, index)) as string
+        } catch {
+          throw new SourceAdapterError('JSON_MALFORMED')
+        }
+      }
+      if (character && character < ' ') throw new SourceAdapterError('JSON_MALFORMED')
+      index += 1
+    }
+    throw new SourceAdapterError('JSON_MALFORMED')
+  }
+  const value = (): unknown => {
+    skip()
+    const character = text[index]
+    if (character === '{') {
+      index += 1
+      const object: Record<string, unknown> = {}
+      const keys = new Set<string>()
+      skip()
+      if (text[index] === '}') {
+        index += 1
+        return object
+      }
+      while (true) {
+        skip()
+        const key = string()
+        if (keys.has(key)) throw new SourceAdapterError('JSON_DUPLICATE_KEY', [key])
+        keys.add(key)
+        skip()
+        if (text[index] !== ':') throw new SourceAdapterError('JSON_MALFORMED')
+        index += 1
+        object[key] = value()
+        skip()
+        if (text[index] === '}') {
+          index += 1
+          return object
+        }
+        if (text[index] !== ',') throw new SourceAdapterError('JSON_MALFORMED')
+        index += 1
+      }
+    }
+    if (character === '[') {
+      index += 1
+      const array: unknown[] = []
+      skip()
+      if (text[index] === ']') {
+        index += 1
+        return array
+      }
+      while (true) {
+        array.push(value())
+        skip()
+        if (text[index] === ']') {
+          index += 1
+          return array
+        }
+        if (text[index] !== ',') throw new SourceAdapterError('JSON_MALFORMED')
+        index += 1
+      }
+    }
+    if (character === '"') return string()
+    const start = index
+    while (index < text.length && !/[\s,\]}]/.test(text[index] ?? '')) index += 1
+    const token = text.slice(start, index)
+    try {
+      return JSON.parse(token) as unknown
+    } catch {
+      throw new SourceAdapterError('JSON_MALFORMED')
+    }
+  }
+  const parsed = value()
+  skip()
+  if (index !== text.length) throw new SourceAdapterError('JSON_MALFORMED')
+  return parsed
+}
+
+function parsePluginEntry(
+  value: unknown,
+  source: SourceConfig,
+  index: number
+): MarketplacePluginEntry {
+  const entry = record(value, 'PLUGIN_ENTRY_NOT_OBJECT', String(index))
+  const name = requiredString(entry.name, 'PLUGIN_NAME_REQUIRED', String(index))
+  const rawSource = entry.source
+  if (rawSource === undefined) throw new SourceAdapterError('PLUGIN_SOURCE_REQUIRED', [name])
+  const sourceSpec = parseSourceSpec(rawSource, source, name)
+  const category = stringValue(entry.category)
+  const categories = [
+    ...(Array.isArray(entry.categories) ? entry.categories.filter(isString) : []),
+    ...(category ? [category] : []),
+  ]
+  return {
+    name,
+    ...(stringValue(entry.displayName) ? { displayName: stringValue(entry.displayName) } : {}),
+    description: stringValue(entry.description) ?? '',
+    categories: uniqueStrings(categories),
+    keywords: uniqueStrings(Array.isArray(entry.keywords) ? entry.keywords.filter(isString) : []),
+    authors: authorNames(entry.author ?? entry.authors),
+    ...(safeOptionalUrl(entry.homepage) ? { homepage: safeOptionalUrl(entry.homepage) } : {}),
+    icons: uniqueStrings(
+      [entry.icon, ...(Array.isArray(entry.icons) ? entry.icons : [])].filter(isString)
+    ),
+    source: sourceSpec,
+    policy: recordOrEmpty(entry.policy),
+    raw: entry,
+    entryDigest: digest(entry),
+  }
+}
+
+export function parseSourceSpec(
+  value: unknown,
+  source: SourceConfig,
+  pluginName = 'unknown'
+): PluginSourceSpec {
+  if (typeof value === 'string') {
+    if (looksLikeUrl(value)) {
+      return { kind: 'git', repositoryUrl: canonicalRepositoryUrl(value), subdirectory: '' }
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value))
+      throw new SourceAdapterError('PLUGIN_SOURCE_SCHEME_UNSUPPORTED', [pluginName, value])
+    return { kind: 'local', path: safeRelativePath(value, `PLUGIN_SOURCE_PATH:${pluginName}`) }
+  }
+  const object = record(value, 'PLUGIN_SOURCE_INVALID', pluginName)
+  const kind = stringValue(object.source) ?? stringValue(object.type)
+  if (kind === 'local') {
+    return {
+      kind: 'local',
+      path: safeRelativePath(requiredString(object.path, 'LOCAL_PATH_REQUIRED', pluginName)),
+    }
+  }
+  if (kind === 'git-subdir' || kind === 'url' || kind === 'git') {
+    const url = canonicalRepositoryUrl(requiredString(object.url, 'GIT_URL_REQUIRED', pluginName))
+    const subdirectory =
+      kind === 'git-subdir'
+        ? safeRelativePath(requiredString(object.path, 'GIT_PATH_REQUIRED', pluginName))
+        : ''
+    const ref = stringValue(object.ref)
+    const sha = stringValue(object.sha)
+    if (sha !== undefined && !/^[a-f0-9]{40}$/.test(sha)) {
+      throw new SourceAdapterError('GIT_SHA_INVALID', [pluginName, sha])
+    }
+    return {
+      kind: 'git',
+      repositoryUrl: url,
+      subdirectory,
+      ...(ref === undefined ? {} : { ref }),
+      ...(sha === undefined ? {} : { sha }),
+    }
+  }
+  throw new SourceAdapterError('PLUGIN_SOURCE_KIND_UNSUPPORTED', [pluginName, kind ?? 'missing'])
+}
+
+export function canonicalRepositoryUrl(input: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(input)
+  } catch {
+    throw new SourceAdapterError('GIT_URL_INVALID', [input])
+  }
+  if (parsed.protocol !== 'https:')
+    throw new SourceAdapterError('GIT_URL_PROTOCOL_UNSUPPORTED', [input])
+  if (parsed.username || parsed.password || parsed.port || parsed.search || parsed.hash) {
+    throw new SourceAdapterError('GIT_URL_CREDENTIALS_OR_QUERY_FORBIDDEN', [input])
+  }
+  const path = parsed.pathname
+    .replace(/\/+/g, '/')
+    .replace(/\/+$/, '')
+    .replace(/\.git$/, '')
+  if (!/^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(path)) {
+    throw new SourceAdapterError('GIT_URL_REPOSITORY_PATH_INVALID', [input])
+  }
+  return `https://${parsed.hostname.toLowerCase()}${path}`
+}
+
+export function safeRelativePath(input: string, code = 'PATH_INVALID'): string {
+  if (!input || input.startsWith('/') || input.startsWith('\\') || /^[A-Za-z]:/.test(input)) {
+    throw new SourceAdapterError(code, [input])
+  }
+  const normalized = input.replaceAll('\\', '/').replace(/^(\.\/)+/, '')
+  if (!normalized) throw new SourceAdapterError(code, [input])
+  const parts = normalized.split('/')
+  if (parts.some((part) => part === '..' || part === '.'))
+    throw new SourceAdapterError('PATH_TRAVERSAL', [input])
+  if (parts.some((part) => part.length === 0)) throw new SourceAdapterError(code, [input])
+  return parts.join('/')
+}
+
+function record(input: unknown, code: string, detail?: string): Record<string, unknown> {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new SourceAdapterError(code, detail ? [detail] : [])
+  }
+  return input as Record<string, unknown>
+}
+
+function recordOrEmpty(input: unknown): Record<string, unknown> {
+  return input && typeof input === 'object' && !Array.isArray(input)
+    ? (input as Record<string, unknown>)
+    : {}
+}
+
+function requiredString(input: unknown, code: string, detail: string): string {
+  const result = stringValue(input)
+  if (!result) throw new SourceAdapterError(code, [detail])
+  return result
+}
+
+function stringValue(input: unknown): string | undefined {
+  return typeof input === 'string' && input.trim() ? input.trim() : undefined
+}
+
+function isString(input: unknown): input is string {
+  return typeof input === 'string' && input.trim().length > 0
+}
+
+function uniqueStrings(input: readonly string[]): string[] {
+  return [...new Set(input.map((value) => value.trim()).filter(Boolean))].toSorted((a, b) =>
+    a.localeCompare(b)
+  )
+}
+
+function authorNames(input: unknown): string[] {
+  if (Array.isArray(input)) return uniqueStrings(input.flatMap((item) => authorNames(item)))
+  if (typeof input === 'string') return uniqueStrings([input])
+  if (input && typeof input === 'object') {
+    const object = input as Record<string, unknown>
+    const name = stringValue(object.name) ?? stringValue(object.email)
+    return name ? [name] : []
+  }
+  return []
+}
+
+function ownerNames(input: unknown): string[] {
+  return authorNames(input)
+}
+
+function safeOptionalUrl(input: unknown): string | undefined {
+  if (!isString(input)) return undefined
+  try {
+    const parsed = new URL(input)
+    return parsed.protocol === 'https:' ? parsed.toString() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function looksLikeUrl(input: string): boolean {
+  return /^https?:\/\//i.test(input)
+}
+
+function digest(value: unknown): string {
+  return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  const object = value as Record<string, unknown>
+  return `{${Object.keys(object)
+    .toSorted()
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)
+    .join(',')}}`
+}