@adea-ai/plugins 3.0.10 → 4.0.0

package/src/index.test.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, mkdir, readFile, symlink, writeFile } from 'node:fs/promises'
+import { chmod, mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { readdirSync, readFileSync } from 'node:fs'
 import { gzipSync } from 'node:zlib'
 import { pack } from 'tar-stream'
@@ -28,7 +28,6 @@ import {
   parseSourceSpec,
   type SourceConfig,
 } from './sources.js'
-import { createMaterializationPlan, supportedHarnesses } from './harness.js'
 
 const sources: SourceConfig[] = [
   {
@@ -409,6 +408,132 @@ describe('deterministic catalog synchronization', () => {
     ).rejects.toThrow('SOURCE_LOCK_PLUGIN_PIN_MISMATCH: pin-test:remote')
   })
 
+  test('refreshes explicit external revisions and repositories outside lock replay', async () => {
+    const fixtureRoot = await mkdtemp(join(tmpdir(), 'plugin-pin-refresh-'))
+    try {
+      await mkdir(join(fixtureRoot, 'pin-test'), { recursive: true })
+      const manifestPath = join(fixtureRoot, 'pin-test', 'marketplace.json')
+      const writeManifest = (sha: string, url = 'https://github.com/acme/remote-plugin') =>
+        writeFile(
+          manifestPath,
+          JSON.stringify({
+            plugins: [
+              {
+                name: 'remote',
+                description: 'Remote fixture plugin.',
+                source: { source: 'git', url, sha },
+              },
+            ],
+          })
+        )
+      const source: SourceConfig = {
+        ...sources[0]!,
+        sourceId: 'pin-test',
+        manifestPath: 'marketplace.json',
+        fixturePath: 'pin-test',
+        fixtureCommitSha: '5'.repeat(40),
+      }
+      const options = {
+        sources: [source],
+        categoryMap,
+        productAliases,
+        policy,
+        mode: 'offline' as const,
+        fixtureRoot,
+        snapshotLoader: {
+          load: async () => ({
+            files: new Map([['plugin.json', new TextEncoder().encode('{"name":"Remote"}')]]),
+            symlinks: [],
+          }),
+        },
+      }
+      await writeManifest('6'.repeat(40))
+      const first = await synchronize(options)
+      await writeManifest('7'.repeat(40))
+      const refreshed = await synchronize({ ...options, existingLock: first.lock! })
+      expect(refreshed.lock?.sources[0]?.pluginPins[0]?.resolvedCommitSha).toBe('7'.repeat(40))
+      expect(refreshed.catalog?.plugins[0]?.availableReleases[0]?.resolvedCommitSha).toBe(
+        '7'.repeat(40)
+      )
+      await writeManifest('8'.repeat(40), 'https://github.com/acme/replacement-plugin')
+      const replaced = await synchronize({ ...options, existingLock: refreshed.lock! })
+      expect(replaced.lock?.sources[0]?.pluginPins[0]?.repositoryUrl).toBe(
+        'https://github.com/acme/replacement-plugin'
+      )
+      expect(replaced.lock?.sources[0]?.pluginPins[0]?.resolvedCommitSha).toBe('8'.repeat(40))
+    } finally {
+      await rm(fixtureRoot, { recursive: true, force: true })
+    }
+  })
+
+  test.skipIf(process.platform === 'win32')(
+    'refreshes floating external refs even when the marketplace head is unchanged',
+    async () => {
+      const bin = await mkdtemp(join(tmpdir(), 'plugin-live-pin-'))
+      const originalPath = process.env.PATH
+      const originalFetch = globalThis.fetch
+      const sourceSha = '5'.repeat(40)
+      const source: SourceConfig = {
+        ...sources[0]!,
+        sourceId: 'live-pin-test',
+        repositoryUrl: 'https://github.com/acme/marketplace',
+        manifestPath: 'marketplace.json',
+      }
+      const manifest = JSON.stringify({
+        plugins: [
+          {
+            name: 'remote',
+            description: 'Remote plugin.',
+            source: { source: 'git', url: 'https://github.com/acme/remote-plugin', ref: 'main' },
+          },
+        ],
+      })
+      const gitPath = join(bin, 'git')
+      const writeGit = async (pluginSha: string) => {
+        await writeFile(
+          gitPath,
+          `#!/bin/sh\nif [ "$2" = "${source.repositoryUrl}" ]; then\n  printf '%s\\t%s\\n' '${sourceSha}' "$3"\nelse\n  printf '%s\\t%s\\n' '${pluginSha}' "$3"\nfi\n`
+        )
+        await chmod(gitPath, 0o700)
+      }
+      try {
+        process.env.PATH = `${bin}:${originalPath ?? ''}`
+        globalThis.fetch = (async (url) => {
+          expect(String(url)).toBe(
+            `https://raw.githubusercontent.com/acme/marketplace/${sourceSha}/marketplace.json`
+          )
+          return new Response(manifest)
+        }) as typeof fetch
+        const options = {
+          sources: [source],
+          categoryMap,
+          productAliases,
+          policy,
+          mode: 'live' as const,
+          snapshotLoader: {
+            load: async () => ({
+              files: new Map([['plugin.json', new TextEncoder().encode('{"name":"Remote"}')]]),
+              symlinks: [],
+            }),
+          },
+        }
+        await writeGit('6'.repeat(40))
+        const first = await synchronize(options)
+        await writeGit('7'.repeat(40))
+        const next = await synchronize({ ...options, existingLock: first.lock! })
+        expect(next.changed).toBe(true)
+        expect(next.lock?.sources[0]?.pluginPins[0]?.resolvedCommitSha).toBe('7'.repeat(40))
+        const replay = await synchronize({ ...options, fromLock: first.lock! })
+        expect(replay.lock?.sources[0]?.pluginPins[0]?.resolvedCommitSha).toBe('6'.repeat(40))
+      } finally {
+        globalThis.fetch = originalFetch
+        if (originalPath === undefined) delete process.env.PATH
+        else process.env.PATH = originalPath
+        await rm(bin, { recursive: true, force: true })
+      }
+    }
+  )
+
   test('skips apollo-skills symlinks deterministically without dropping safe plugins', async () => {
     const fixtureRoot = await mkdtemp(join(tmpdir(), 'apollo-symlink-'))
     await mkdir(join(fixtureRoot, 'apollo'), { recursive: true })
@@ -537,37 +662,6 @@ describe('identity, classification, and harness contracts', () => {
     )
     expect(normalizeCategory('Developer Tools', categoryMap)).toBe('developer-tools')
   })
-
-  test('generates a deterministic non-installing plan for every harness', async () => {
-    const result = await synchronize({
-      sources,
-      categoryMap,
-      productAliases,
-      policy,
-      mode: 'offline',
-      fixtureRoot: join(process.cwd(), 'fixtures'),
-    })
-    const catalog = result.catalog!
-    for (const harness of supportedHarnesses()) {
-      const plan = createMaterializationPlan({
-        catalog,
-        pluginId: 'plugin:openai-official:linear',
-        harness,
-      })
-      expect(plan.pluginId).toBe('plugin:openai-official:linear')
-      expect(plan.configuration.executeInstallation).toBe(false)
-      expect(JSON.stringify(plan)).toBe(
-        JSON.stringify(
-          createMaterializationPlan({
-            catalog,
-            pluginId: plan.pluginId,
-            harness,
-            releaseId: plan.releaseId,
-          })
-        )
-      )
-    }
-  })
 })
 
 describe('filesystem safety', () => {
@@ -699,9 +793,13 @@ describe('upstream fetch quarantine', () => {
   })
 
   test('quarantines a plugin when the archive keeps failing', async () => {
-    const stub = stubFetch((url) => {
+    let recovered = false
+    const stub = stubFetch(async (url) => {
       if (url === treeUrl) return jsonResponse(treePayload(['plugins/demo/plugin.json']))
-      if (isArchive(url)) return new Response('broken', { status: 500 })
+      if (isArchive(url))
+        return recovered
+          ? tarballResponse([{ path: 'plugins/demo/plugin.json', body: manifestBytes }])
+          : new Response('broken', { status: 500 })
       return new Response('unexpected', { status: 200 })
     })
     try {
@@ -712,6 +810,9 @@ describe('upstream fetch quarantine', () => {
       )
       expect(error?.message).toMatch(/^PLUGIN_SOURCE_UNAVAILABLE:/)
       expect(stub.calls.filter(isArchive)).toHaveLength(3)
+      recovered = true
+      expect((await loader.load(repo, sha, 'plugins/demo')).files.has('plugin.json')).toBe(true)
+      expect(stub.calls.filter(isArchive)).toHaveLength(4)
     } finally {
       stub.restore()
     }
@@ -745,11 +846,15 @@ describe('upstream fetch quarantine', () => {
 
   test('does not retry a forbidden tree without rate-limit signals', async () => {
     let treeCalls = 0
-    const stub = stubFetch((url) => {
+    const stub = stubFetch(async (url) => {
       if (url === treeUrl) {
         treeCalls += 1
-        return new Response('denied', { status: 403 })
+        return treeCalls === 1
+          ? new Response('denied', { status: 403 })
+          : jsonResponse(treePayload(['plugins/demo/plugin.json']))
       }
+      if (isArchive(url))
+        return tarballResponse([{ path: 'plugins/demo/plugin.json', body: manifestBytes }])
       return new Response('unexpected', { status: 500 })
     })
     try {
@@ -760,6 +865,8 @@ describe('upstream fetch quarantine', () => {
       )
       expect(error?.message).toMatch(/^PLUGIN_SOURCE_UNAVAILABLE:/)
       expect(treeCalls).toBe(1)
+      expect((await loader.load(repo, sha, 'plugins/demo')).files.has('plugin.json')).toBe(true)
+      expect(treeCalls).toBe(2)
     } finally {
       stub.restore()
     }
@@ -779,11 +886,14 @@ describe('upstream fetch quarantine', () => {
     })
     try {
       const loader = new NetworkSnapshotLoader(policy)
-      const first = await loader.load(repo, sha, 'plugins/one')
-      const second = await loader.load(repo, sha, 'plugins/two')
+      const [first, second] = await Promise.all([
+        loader.load(repo, sha, 'plugins/one'),
+        loader.load(repo, sha, 'plugins/two'),
+      ])
       expect([...first.files.keys()]).toEqual(['plugin.json'])
       expect([...second.files.keys()].toSorted()).toEqual(['plugin.json', 'run.sh'])
-      // The whole point: three files, and the archive is fetched once.
+      // Concurrent plugins share both requests, not only the finished cache.
+      expect(stub.calls.filter((url) => url === treeUrl)).toHaveLength(1)
       expect(stub.calls.filter(isArchive)).toHaveLength(1)
       expect(stub.calls.filter(isRawGitHubHost)).toHaveLength(0)
     } finally {

package/src/index.ts

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { Readable } from 'node:stream'
+import { setTimeout as sleep } from 'node:timers/promises'
 import { createGunzip } from 'node:zlib'
 import { extract } from 'tar-stream'
 import {
@@ -59,6 +60,9 @@ import {
 } from './site-icons.js'
 import { normalizeDisplayName } from './display-name.js'
 import { immutableAssetUrl } from './publication.js'
+import { sourceDigest as bytesDigest } from './source-digest.js'
+
+export { bytesDigest }
 
 /**
  * Marks the catalog format this compiler emits.
@@ -297,17 +301,6 @@ export function digest(value: unknown): string {
   return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`
 }
 
-export function bytesDigest(files: ReadonlyMap<string, Uint8Array>): string {
-  const hash = createHash('sha256')
-  for (const [path, bytes] of [...files.entries()].toSorted(([left], [right]) =>
-    left.localeCompare(right)
-  )) {
-    hash.update(`${path.length}:${path}:${bytes.byteLength}:`)
-    hash.update(bytes)
-  }
-  return `sha256:${hash.digest('hex')}`
-}
-
 export function stablePluginId(sourceId: string, upstreamName: string): string {
   return `plugin:${slug(sourceId)}:${slug(upstreamName)}`
 }
@@ -463,6 +456,7 @@ export async function buildCatalog(input: {
       ...(input.productCategories ? { productCategories: input.productCategories } : {}),
       ...(input.leading ? { leading: input.leading } : {}),
       ...(input.productIconOverrides ? { productIconOverrides: input.productIconOverrides } : {}),
+      ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
     })
   ).catalog
 }
@@ -2002,7 +1996,10 @@ async function resolvePluginPins(input: {
 
       const repositoryUrl = canonicalRepositoryUrl(entry.source.repositoryUrl)
       const pluginSubdirectory = entry.source.subdirectory
-      const locked = input.lockedPins?.find((pin) => pin.pluginName === entry.name)
+      // Existing locks describe the prior sync; only explicit replay freezes revisions.
+      const locked = input.fromLock
+        ? input.lockedPins?.find((pin) => pin.pluginName === entry.name)
+        : undefined
       if (input.fromLock && !locked)
         throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISSING: ${input.config.sourceId}:${entry.name}`)
       if (locked) {
@@ -2192,10 +2189,6 @@ const UPSTREAM_WEATHER_SKIP_CODES: ReadonlySet<PluginSkipReasonCode> = new Set([
   'PLUGIN_PATH_NOT_FOUND',
 ])
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms))
-}
-
 function upstreamRetryDelayMs(attempt: number, response?: Response): number {
   const retryAfter = response?.headers.get('retry-after')
   if (retryAfter !== null && retryAfter !== undefined) {
@@ -2230,8 +2223,8 @@ async function fetchUpstream(url: string, init: RequestInit): Promise<Response>
     try {
       response = await fetch(url, init)
     } catch (error) {
-      if (attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
-      await sleep(upstreamRetryDelayMs(attempt))
+      if (init.signal?.aborted || attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
+      await sleep(upstreamRetryDelayMs(attempt), undefined, { signal: init.signal ?? undefined })
       attempt += 1
       continue
     }
@@ -2241,7 +2234,10 @@ async function fetchUpstream(url: string, init: RequestInit): Promise<Response>
       attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1
     )
       return response
-    await sleep(upstreamRetryDelayMs(attempt, response))
+    await response.body?.cancel().catch(() => {})
+    await sleep(upstreamRetryDelayMs(attempt, response), undefined, {
+      signal: init.signal ?? undefined,
+    })
     attempt += 1
   }
 }
@@ -2343,8 +2339,8 @@ export async function readArchiveFiles(
 
 export class NetworkSnapshotLoader implements SnapshotLoader {
   readonly #policy: CatalogPolicy
-  readonly #trees = new Map<string, readonly TreeEntry[]>()
-  readonly #archives = new Map<string, ReadonlyMap<string, Uint8Array>>()
+  readonly #trees = new Map<string, Promise<readonly TreeEntry[]>>()
+  readonly #archives = new Map<string, Promise<ReadonlyMap<string, Uint8Array>>>()
 
   constructor(policy: CatalogPolicy) {
     this.#policy = policy
@@ -2361,22 +2357,28 @@ export class NetworkSnapshotLoader implements SnapshotLoader {
     const [owner, repo] = parsed.pathname.split('/').filter(Boolean)
     if (!owner || !repo) throw new Error('GIT_REPOSITORY_INVALID')
     const key = `${owner}/${repo}@${commitSha}`
-    let tree = this.#trees.get(key)
-    if (!tree) {
-      const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitSha}?recursive=1`
-      const response = await fetchUpstream(treeUrl, {
-        headers: upstreamRequestHeaders(treeUrl),
+    let pendingTree = this.#trees.get(key)
+    if (!pendingTree) {
+      pendingTree = (async () => {
+        const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitSha}?recursive=1`
+        const response = await fetchUpstream(treeUrl, {
+          headers: upstreamRequestHeaders(treeUrl),
+        })
+        if (!response.ok)
+          throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
+        const payload = (await response.json()) as { truncated?: boolean; tree?: TreeEntry[] }
+        if (payload.truncated) throw new Error(`GIT_TREE_TRUNCATED: ${owner}/${repo}@${commitSha}`)
+        return (payload.tree ?? []).map((entry) => ({
+          ...entry,
+          path: safeRelativePath(entry.path, 'TREE_PATH_INVALID'),
+        }))
+      })().catch((error: unknown) => {
+        this.#trees.delete(key)
+        throw error
       })
-      if (!response.ok)
-        throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
-      const payload = (await response.json()) as { truncated?: boolean; tree?: TreeEntry[] }
-      if (payload.truncated) throw new Error(`GIT_TREE_TRUNCATED: ${owner}/${repo}@${commitSha}`)
-      tree = (payload.tree ?? []).map((entry) => ({
-        ...entry,
-        path: safeRelativePath(entry.path, 'TREE_PATH_INVALID'),
-      }))
-      this.#trees.set(key, tree)
+      this.#trees.set(key, pendingTree)
     }
+    const tree = await pendingTree
     const prefix = pluginSubdirectory ? `${safeRelativePath(pluginSubdirectory)}/` : ''
     const submodules = tree.filter(
       (entry) =>
@@ -2428,12 +2430,18 @@ export class NetworkSnapshotLoader implements SnapshotLoader {
   ): Promise<ReadonlyMap<string, Uint8Array>> {
     const cached = this.#archives.get(key)
     if (cached) return cached
-    const url = `https://api.github.com/repos/${owner}/${repo}/tarball/${commitSha}`
-    const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) })
-    if (!response.ok) throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
-    const files = await readArchiveFiles(new Uint8Array(await response.arrayBuffer()), this.#policy)
-    this.#archives.set(key, files)
-    return files
+    const pending = (async () => {
+      const url = `https://api.github.com/repos/${owner}/${repo}/tarball/${commitSha}`
+      const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) })
+      if (!response.ok)
+        throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
+      return readArchiveFiles(new Uint8Array(await response.arrayBuffer()), this.#policy)
+    })().catch((error: unknown) => {
+      this.#archives.delete(key)
+      throw error
+    })
+    this.#archives.set(key, pending)
+    return pending
   }
 }
 

package/src/portable-catalog.test.ts

@@ -12,7 +12,7 @@ import {
   PACKAGE_METADATA_KEY,
 } from './portable-catalog.js'
 import { verifyAgentPackage, materializeAgentPackage } from './agent-plugins-catalog.js'
-import { createCatalogInstallationPlan, createInstallationPlan } from './agent-plugins-harness.js'
+import { createCatalogInstallationPlan, createInstallationPlan } from './harness.js'
 import type { HarnessProfile } from './agent-plugins-schema.js'
 import { snapshotFromDirectory } from './index.js'
 import {
@@ -351,7 +351,7 @@ it('refuses a malformed provenance descriptor with one typed line naming the plu
   }))
 
 const CONSUMER_SCRIPT = `import { readFileSync } from 'node:fs'
-import { createCatalogInstallationPlan } from '@adea-ai/plugins/agent-plugins/harness'
+import { createCatalogInstallationPlan } from '@adea-ai/plugins/harness'
 import { synchronizePortable } from '@adea-ai/plugins/portable-catalog'
 import { digest } from '@adea-ai/plugins'
 const request = JSON.parse(readFileSync(process.argv[2], 'utf8'))
@@ -377,7 +377,7 @@ try {
       ok: true,
       plan,
       catalogId: result.catalog.catalogId,
-      resolvedHarness: import.meta.resolve('@adea-ai/plugins/agent-plugins/harness'),
+      resolvedHarness: import.meta.resolve('@adea-ai/plugins/harness'),
       resolvedCatalog: import.meta.resolve('@adea-ai/plugins/portable-catalog'),
     })
   )
@@ -475,7 +475,7 @@ it('keeps the packed consumer inside the packed artifact and its own dependencie
     // The packed artifact was built from the CURRENT source: a stale build
     // would still carry the sentinel the rebuild removes.
     assert.equal(consumer.builtFromCurrentSource, true)
-    assert.equal(existsSync(join(consumer.packedRoot, 'dist', 'agent-plugins-harness.js')), true)
+    assert.equal(existsSync(join(consumer.packedRoot, 'dist', 'harness.js')), true)
     // Every copied dependency really resolves INSIDE the consumer: the
     // workspace installs them as links into the package manager's store, so
     // a copy that kept the link would resolve outside the consumer.
@@ -487,7 +487,10 @@ it('keeps the packed consumer inside the packed artifact and its own dependencie
     // dependencies, and never the whole workspace.
     const packedManifest = JSON.parse(
       await readFile(join(consumer.packedRoot, 'package.json'), 'utf8')
-    ) as { dependencies?: Record<string, string> }
+    ) as { dependencies?: Record<string, string>; exports: Record<string, unknown> }
+    assert.ok(packedManifest.exports['./harness'])
+    assert.equal(packedManifest.exports['./agent-plugins/harness'], undefined)
+    assert.equal(existsSync(join(consumer.packedRoot, 'dist', 'agent-plugins-harness.js')), false)
     const declared = Object.keys(packedManifest.dependencies ?? {})
     for (const name of declared) assert.ok(consumer.linkedDependencies.includes(name))
     const installed = await readdir(join(consumer.consumerRoot, 'node_modules'))

package/src/schema.ts

@@ -248,45 +248,6 @@ export const SourcesLockSchema = z
   })
   .strict()
 
-export const MaterializationPlanSchema = z
-  .object({
-    planVersion: z.literal(1),
-    pluginId: PluginSchema.shape.pluginId,
-    releaseId: PluginReleaseSchema.shape.releaseId,
-    harness: HarnessSchema,
-    source: z
-      .object({
-        repositoryUrl: z.string().url(),
-        commitSha: ShaSchema,
-        pluginSubdirectory: z.string().min(1),
-        contentDigest: DigestSchema,
-      })
-      .strict(),
-    targetLayout: z
-      .object({
-        root: z.string().min(1),
-        notes: z.array(z.string().min(1)).max(32),
-      })
-      .strict(),
-    files: z
-      .array(
-        z
-          .object({
-            sourcePath: z.string().min(1),
-            targetPath: z.string().min(1),
-            action: z.enum(['copy', 'translate', 'ignore', 'unsupported']),
-            reason: z.string().min(1).max(500),
-          })
-          .strict()
-      )
-      .max(4096),
-    configuration: JsonObjectSchema,
-    requiredConnectors: z.array(z.string().min(1)).max(128),
-    requiredCredentials: z.array(z.string().min(1)).max(128),
-    policyConstraints: z.array(z.string().min(1)).max(128),
-  })
-  .strict()
-
 export type CatalogSource = z.output<typeof CatalogSourceSchema>
 export type Capability = z.output<typeof CapabilitySchema>
 export type HarnessCompatibility = z.output<typeof HarnessCompatibilitySchema>
@@ -298,7 +259,6 @@ export type Plugin = z.output<typeof PluginSchema>
 export type Catalog = z.output<typeof CatalogSchema>
 export type SourceLockEntry = z.output<typeof SourceLockEntrySchema>
 export type SourcesLock = z.output<typeof SourcesLockSchema>
-export type MaterializationPlan = z.output<typeof MaterializationPlanSchema>
 
 export function parseCatalog(input: unknown): Catalog {
   return CatalogSchema.parse(input)

package/src/site-icon-fallback.test.ts

@@ -1,3 +1,6 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { describe, expect, test } from 'bun:test'
 import {
   buildCatalog,
@@ -12,7 +15,7 @@ import {
 } from './index.js'
 import { buildConsumerIndex } from './consumer-index.js'
 import { resolveIconSources, stageIconAssets } from './icon-mirror.js'
-import { selectIconPath } from './icons.js'
+import { iconAssetName, selectIconPath } from './icons.js'
 
 /**
  * End-to-end cover for the brand-mark fallback: a plugin that ships no mark of
@@ -23,8 +26,8 @@ import { selectIconPath } from './icons.js'
 const PNG = new Uint8Array([
   0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
 ])
-const HOME = 'https://vendor.example/'
-const APPLE_ICON = 'https://vendor.example/apple-icon.png'
+const HOME = 'https://fc-vendor.example/'
+const APPLE_ICON = 'https://fd-cdn.example/apple-icon.png'
 
 const policy: CatalogPolicy = {
   allowedRepositoryHosts: ['github.com'],
@@ -98,10 +101,14 @@ function stubFetch(handler: (url: string) => Response) {
   return { calls, restore: () => void (globalThis.fetch = original) }
 }
 
-async function build(entryName: string, homepage?: string, options: { live?: boolean } = {}) {
+async function build(
+  entryName: string,
+  homepage?: string,
+  options: { live?: boolean; iconAssetsDirectory?: string } = {}
+) {
   const stub = stubFetch((url) => {
     if (url === HOME)
-      return new Response(`<head><link rel="apple-touch-icon" href="/apple-icon.png"></head>`, {
+      return new Response(`<head><link rel="apple-touch-icon" href="${APPLE_ICON}"></head>`, {
         status: 200,
       })
     if (url === APPLE_ICON) return new Response(PNG, { status: 200 })
@@ -116,6 +123,7 @@ async function build(entryName: string, homepage?: string, options: { live?: boo
       metadataOnly: false,
       snapshotLoader: loader({ 'README.md': new TextEncoder().encode('no mark here') }),
       resolveExternalRefs: options.live ?? true,
+      ...(options.iconAssetsDirectory ? { iconAssetsDirectory: options.iconAssetsDirectory } : {}),
     })
     return { catalog, calls: stub.calls }
   } finally {
@@ -124,18 +132,26 @@ async function build(entryName: string, homepage?: string, options: { live?: boo
 }
 
 describe('product site icon fallback', () => {
-  test('records the site icon for a plugin that ships no mark', async () => {
-    const { catalog, calls } = await build('connector', HOME)
-    const release = catalog.plugins[0]!.availableReleases[0]!
-    expect(release.icon).toEqual({
-      kind: 'favicon',
-      url: APPLE_ICON,
-      homepage: HOME,
-      contentType: 'image/png',
-      digest: byteDigest(PNG),
-      bytes: PNG.byteLength,
-    })
-    expect(calls).toEqual([HOME, APPLE_ICON])
+  test('records and stages the site icon for a plugin that ships no mark', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'catalog-icons-'))
+    try {
+      const { catalog, calls } = await build('connector', HOME, { iconAssetsDirectory: directory })
+      const release = catalog.plugins[0]!.availableReleases[0]!
+      expect(release.icon).toEqual({
+        kind: 'favicon',
+        url: APPLE_ICON,
+        homepage: HOME,
+        contentType: 'image/png',
+        digest: byteDigest(PNG),
+        bytes: PNG.byteLength,
+      })
+      expect(calls).toEqual([HOME, APPLE_ICON])
+      expect(await readFile(join(directory, iconAssetName(byteDigest(PNG), 'image/png')))).toEqual(
+        Buffer.from(PNG)
+      )
+    } finally {
+      await rm(directory, { recursive: true, force: true })
+    }
   })
 
   test('prefers the plugin content and never contacts the site when a mark exists', async () => {
@@ -148,15 +164,16 @@ describe('product site icon fallback', () => {
         policy,
         metadataOnly: false,
         snapshotLoader: loader({
-          'assets/logo.svg': new TextEncoder().encode(
+          'assets/brand.svg': new TextEncoder().encode(
             '<svg xmlns="http://www.w3.org/2000/svg"><rect width="8" height="8"/></svg>'
           ),
+          'assets/icon.png': PNG,
         }),
         resolveExternalRefs: true,
       })
       expect(catalog.plugins[0]!.availableReleases[0]!.icon).toMatchObject({
         kind: 'content',
-        path: 'assets/logo.svg',
+        path: 'assets/icon.png',
       })
       expect(stub.calls).toEqual([])
     } finally {

package/src/site-icons.test.ts

@@ -71,6 +71,10 @@ describe('vendor homepage eligibility', () => {
     expect(isPublicHostname('bare-hostname')).toBe(false)
     expect(isPublicHostname('::1')).toBe(false)
     expect(isPublicHostname('fd00::1')).toBe(false)
+    expect(isPublicHostname('[fc00::1]')).toBe(false)
+    expect(isPublicHostname('fe80::1')).toBe(false)
+    expect(isPublicHostname('fc-vendor.example')).toBe(true)
+    expect(isPublicHostname('fd-cdn.example')).toBe(true)
   })
 })
 
@@ -100,6 +104,33 @@ describe('site icon discovery', () => {
     )
   })
 
+  test('accepts unquoted HTML attributes without reading the next attribute as rel', () => {
+    expect(
+      discoverSiteIcons('<link rel=icon href=/mark.svg sizes=32x32>', 'https://vendor.example/')
+    ).toEqual(['https://vendor.example/mark.svg', 'https://vendor.example/favicon.ico'])
+  })
+
+  test('only reads actual link attributes and complete relation tokens', () => {
+    const attributesHtml = `<link data-rel="icon" href="/data-rel.png">
+      <link rel="not-icon" href="/not-icon.png">
+      <link rel="stylesheet" title="rel=icon" href="/style.css">
+      <link-preview rel="icon" href="/custom.png">
+      <link rel="icon" data-href="/data-href.png" href="/real.png">`
+    expect(discoverSiteIcons(attributesHtml, 'https://vendor.example/')).toEqual([
+      'https://vendor.example/real.png',
+      'https://vendor.example/favicon.ico',
+    ])
+  })
+
+  test('does not end a link tag at a greater-than character inside a quoted attribute', () => {
+    expect(
+      discoverSiteIcons(
+        '<link title="a > b" rel="icon" href="/mark.svg">',
+        'https://vendor.example/'
+      )
+    ).toEqual(['https://vendor.example/mark.svg', 'https://vendor.example/favicon.ico'])
+  })
+
   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',