@adea-ai/plugins 4.0.0 → 4.0.1

package/src/consumer-index.ts

@@ -194,7 +194,11 @@ export interface ConsumerCategory {
 export interface LeadingDiagnostic {
   readonly category: string
   readonly name: string
-  readonly reason: 'UNKNOWN_CATEGORY' | 'PRODUCT_NOT_FOUND' | 'PRODUCT_NOT_IN_CATEGORY'
+  readonly reason:
+    | 'UNKNOWN_CATEGORY'
+    | 'PRODUCT_NOT_FOUND'
+    | 'PRODUCT_NOT_IN_CATEGORY'
+    | 'PRODUCT_AMBIGUOUS'
 }
 
 /** Brand-mark coverage, so an incomplete set is visible rather than implied. */
@@ -257,10 +261,10 @@ function selectCanonical(
     const index = preference.sourcePreference.indexOf(plugin.sourceId)
     return index === -1 ? preference.sourcePreference.length : index
   }
-  // A variant with no resolved release repository proves nothing about its
+  // A variant with no resolved current-release repository proves nothing about its
   // origin, so it is treated as marketplace-shipped rather than vendor-published.
   const vendorPublished = (plugin: Plugin): boolean => {
-    const repository = plugin.availableReleases[0]?.resolvedRepositoryUrl
+    const repository = currentRelease(plugin)?.resolvedRepositoryUrl
     return repository !== undefined && repository !== sourceRepository.get(plugin.sourceId)
   }
   return [...variants].toSorted(
@@ -417,7 +421,8 @@ export function buildConsumerIndex(input: {
     sourcePreference: [...DEFAULT_SOURCE_PREFERENCE],
   }
   const leading = input.leading ?? {}
-  const topCount = input.topCount ?? DEFAULT_TOP_COUNT
+  const topCount = input.topCount === undefined ? DEFAULT_TOP_COUNT : input.topCount
+  if (!Number.isSafeInteger(topCount) || topCount < 0) throw new Error('TOP_COUNT_INVALID')
   const sourceRepository = new Map(
     input.catalog.sources.map((source) => [source.sourceId, source.repositoryUrl])
   )
@@ -503,18 +508,28 @@ export function buildConsumerIndex(input: {
   const curatedByCategory = new Map<string, string[]>()
   for (const category of categoryNames) {
     const members = input.catalog.plugins.filter((plugin) => plugin.categories.includes(category))
+    const categoryProducts = new Set(members.map((plugin) => plugin.productGroupingKey))
     const curated: string[] = []
     for (const name of leading[category] ?? []) {
-      const matches = members.filter((plugin) => plugin.upstreamPluginName === name)
-      if (matches.length === 0) {
+      const matches = input.catalog.plugins.filter((plugin) => plugin.upstreamPluginName === name)
+      const keys = new Set(
+        matches
+          .map((plugin) => plugin.productGroupingKey)
+          .filter((key) => categoryProducts.has(key))
+      )
+      if (keys.size === 0) {
         diagnostics.push({
           category,
           name,
-          reason: variantsByProduct.has(name) ? 'PRODUCT_NOT_IN_CATEGORY' : 'PRODUCT_NOT_FOUND',
+          reason: matches.length > 0 ? 'PRODUCT_NOT_IN_CATEGORY' : 'PRODUCT_NOT_FOUND',
         })
         continue
       }
-      const key = matches[0]!.productGroupingKey
+      if (keys.size > 1) {
+        diagnostics.push({ category, name, reason: 'PRODUCT_AMBIGUOUS' })
+        continue
+      }
+      const key = keys.values().next().value!
       if (!curated.includes(key)) curated.push(key)
     }
     curatedByCategory.set(category, curated)

package/src/default-head.test.ts

@@ -0,0 +1,143 @@
+import { execFileSync } from 'node:child_process'
+import { chmod, mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { expect, test } from 'bun:test'
+import { buildCatalog, digest, synchronize } from './index.js'
+import { parseMarketplaceManifest } from './sources.js'
+import { withPortableFixture } from '../test-support/portable-fixture.js'
+
+test.skipIf(process.platform === 'win32')(
+  'resolves unspecified external refs from the remote default branch',
+  () =>
+    withPortableFixture(async (input, root) => {
+      const repo = join(root, 'repository')
+      const bin = join(root, 'bin')
+      const originalPath = process.env.PATH
+      const originalGit = process.env.ADEA_TEST_REAL_GIT
+      const originalRepo = process.env.ADEA_TEST_HEAD_REPO
+      const originalFetch = globalThis.fetch
+      const realGit = execFileSync('which', ['git'], { encoding: 'utf8' }).trim()
+      const git = (...args: string[]) =>
+        execFileSync(realGit, ['-C', repo, ...args], { encoding: 'utf8' }).trim()
+      try {
+        await mkdir(repo)
+        await mkdir(bin)
+        git('init', '-q', '-b', 'legacy')
+        git(
+          '-c',
+          'user.name=Fixture',
+          '-c',
+          'user.email=fixture@example.invalid',
+          'commit',
+          '--allow-empty',
+          '-qm',
+          'main commit'
+        )
+        git('branch', 'main')
+        const mainCommit = git('rev-parse', 'refs/heads/main')
+        git(
+          '-c',
+          'user.name=Fixture',
+          '-c',
+          'user.email=fixture@example.invalid',
+          'commit',
+          '--allow-empty',
+          '-qm',
+          'default commit'
+        )
+        const defaultCommit = git('rev-parse', 'HEAD')
+        expect(defaultCommit).not.toBe(mainCommit)
+        const sourceSha = '5'.repeat(40)
+        const source = {
+          ...input.sources[0]!,
+          repositoryUrl: 'https://github.com/acme/marketplace',
+        }
+        const script = join(bin, 'git')
+        await writeFile(
+          script,
+          `#!/bin/sh\nif [ "$2" = "${source.repositoryUrl}" ]; then\n  printf '%s\\t%s\\n' '${sourceSha}' "$3"\nelse\n  shift 2\n  exec "$ADEA_TEST_REAL_GIT" ls-remote "$ADEA_TEST_HEAD_REPO" "$@"\nfi\n`
+        )
+        await chmod(script, 0o700)
+        process.env.ADEA_TEST_REAL_GIT = realGit
+        process.env.ADEA_TEST_HEAD_REPO = repo
+        process.env.PATH = `${bin}:${originalPath ?? ''}`
+        const url = 'https://github.com/acme/remote-plugin'
+        const manifest = JSON.stringify({
+          plugins: [
+            { name: 'object-source', source: { source: 'git', url } },
+            { name: 'url-source', source: url },
+            { name: 'subdir-source', source: { source: 'git-subdir', url, path: 'plugins/demo' } },
+            { name: 'explicit-main', source: { source: 'git', url, ref: 'main' } },
+          ],
+        })
+        globalThis.fetch = (async (_url: unknown) => new Response(manifest)) as typeof fetch
+        const options = {
+          ...input,
+          sources: [source],
+          mode: 'live' as const,
+          snapshotLoader: {
+            load: async () => ({
+              files: new Map([['plugin.json', new TextEncoder().encode('{"name":"Remote"}')]]),
+              symlinks: [],
+            }),
+          },
+        }
+        const result = await synchronize(options)
+        const pins = Object.fromEntries(
+          result.lock!.sources[0]!.pluginPins.map((pin) => [pin.pluginName, pin.resolvedCommitSha])
+        )
+        expect(pins).toEqual({
+          'object-source': defaultCommit,
+          'url-source': defaultCommit,
+          'subdir-source': defaultCommit,
+          'explicit-main': mainCommit,
+        })
+        const direct = await buildCatalog({
+          resolvedSources: [
+            {
+              config: source,
+              commitSha: sourceSha,
+              manifestText: manifest,
+              parsed: parseMarketplaceManifest(JSON.parse(manifest), source),
+              pluginPins: [],
+              retrievedAt: '2026-01-01T00:00:00.000Z',
+              manifestDigest: digest(manifest),
+            },
+          ],
+          categoryMap: input.categoryMap,
+          productAliases: input.productAliases,
+          policy: input.policy,
+          snapshotLoader: options.snapshotLoader,
+          resolveExternalRefs: true,
+        })
+        expect(
+          direct.plugins.find((plugin) => plugin.upstreamPluginName === 'url-source')
+            ?.availableReleases[0]?.resolvedCommitSha
+        ).toBe(defaultCommit)
+        git('symbolic-ref', 'HEAD', 'refs/heads/main')
+        const replay = await synchronize({ ...options, fromLock: result.lock! })
+        expect(
+          replay.lock!.sources[0]!.pluginPins.find((pin) => pin.pluginName === 'url-source')
+            ?.resolvedCommitSha
+        ).toBe(defaultCommit)
+        const refreshed = await synchronize({ ...options, existingLock: result.lock! })
+        expect(refreshed.changed).toBe(true)
+        expect(
+          refreshed.lock!.sources[0]!.pluginPins.find((pin) => pin.pluginName === 'url-source')
+            ?.resolvedCommitSha
+        ).toBe(mainCommit)
+        git('branch', 'x/HEAD', 'main')
+        git('symbolic-ref', 'HEAD', 'refs/heads/missing')
+        expect(git('ls-remote', repo, 'HEAD')).toContain('refs/heads/x/HEAD')
+        await expect(synchronize(options)).rejects.toThrow('GIT_REF_NOT_FOUND')
+      } finally {
+        globalThis.fetch = originalFetch
+        if (originalPath === undefined) delete process.env.PATH
+        else process.env.PATH = originalPath
+        if (originalGit === undefined) delete process.env.ADEA_TEST_REAL_GIT
+        else process.env.ADEA_TEST_REAL_GIT = originalGit
+        if (originalRepo === undefined) delete process.env.ADEA_TEST_HEAD_REPO
+        else process.env.ADEA_TEST_HEAD_REPO = originalRepo
+      }
+    })
+)

package/src/icon-mirror.ts

@@ -4,6 +4,7 @@ import type { Catalog } from './schema.js'
 import { byteDigest, type PublishedAsset } from './index.js'
 import { iconAssetName, inspectIconBytes, type IconContentType } from './icons.js'
 import type { ConsumerIndex } from './consumer-index.js'
+import { writeFileAtomically } from './catalog-store.js'
 
 /**
  * Where an icon's bytes come from, so a mirror needs no tree walk and no
@@ -44,22 +45,27 @@ export interface IconMirrorResult {
 
 /**
  * Maps every mirrored icon back to the exact commit it was resolved from, by
- * matching the digest the product advertises. Canonical variants are inspected
- * first, mirroring the order product records were built in.
+ * matching the digest the product advertises. Retain each distinct pinned
+ * origin so the mirror can try another source if one is unavailable.
  */
 export function resolveIconSources(
   catalog: Pick<Catalog, 'plugins'>,
   index: ConsumerIndex
 ): readonly IconSource[] {
-  const byAsset = new Map<string, IconSource>()
+  const byAsset = new Map<string, IconSource[]>()
+  const add = (source: IconSource) => {
+    const candidates = byAsset.get(source.asset) ?? []
+    if (!candidates.some((candidate) => JSON.stringify(candidate) === JSON.stringify(source)))
+      candidates.push(source)
+    byAsset.set(source.asset, candidates)
+  }
   for (const plugin of catalog.plugins) {
     for (const release of plugin.availableReleases) {
       const icon = release.icon
       if (!icon) continue
       const asset = iconAssetName(icon.digest, icon.contentType)
-      if (byAsset.has(asset)) continue
       if (icon.kind === 'favicon') {
-        byAsset.set(asset, {
+        add({
           kind: 'favicon',
           asset,
           digest: icon.digest,
@@ -74,7 +80,7 @@ export function resolveIconSources(
         release.pluginSubdirectory && release.pluginSubdirectory !== '.'
           ? release.pluginSubdirectory
           : ''
-      byAsset.set(asset, {
+      add({
         kind: 'content',
         asset,
         digest: icon.digest,
@@ -88,14 +94,12 @@ export function resolveIconSources(
       })
     }
   }
-  const sources: IconSource[] = []
+  const selected = new Set<string>()
   for (const product of Object.values(index.products)) {
     const icon = product.icon
-    if (!icon) continue
-    const source = byAsset.get(icon.asset)
-    if (source) sources.push(source)
+    if (icon) selected.add(icon.asset)
   }
-  return sources.toSorted((left, right) => left.asset.localeCompare(right.asset))
+  return [...selected].toSorted().flatMap((asset) => byAsset.get(asset) ?? [])
 }
 
 /**
@@ -113,49 +117,58 @@ export async function stageIconAssets(input: {
   readonly readBytes: (source: IconSource) => Promise<Uint8Array>
 }): Promise<IconMirrorResult> {
   const staged: PublishedAsset[] = []
-  const skipped: { asset: string; reason: string }[] = []
+  const skipped = new Map<string, string>()
+  const complete = new Set<string>()
+  const skip = (asset: string, reason: string) => {
+    if (!skipped.has(asset)) skipped.set(asset, reason)
+  }
   await fs.mkdir(input.assetsDirectory, { recursive: true })
   for (const source of input.sources) {
+    if (complete.has(source.asset)) continue
     const destination = join(input.assetsDirectory, source.asset)
     const existing = await fs.readFile(destination).catch(() => undefined)
     if (existing && byteDigest(existing) === source.digest) {
       staged.push(publishedAssetOf(source))
+      complete.add(source.asset)
+      skipped.delete(source.asset)
       continue
     }
     if (existing) {
-      skipped.push({ asset: source.asset, reason: 'ASSET_CONFLICT' })
+      skip(source.asset, 'ASSET_CONFLICT')
       continue
     }
     let bytes: Uint8Array
     try {
       bytes = await input.readBytes(source)
     } catch (error) {
-      skipped.push({
-        asset: source.asset,
-        reason: `FETCH_FAILED: ${error instanceof Error ? error.message : String(error)}`,
-      })
+      skip(source.asset, `FETCH_FAILED: ${error instanceof Error ? error.message : String(error)}`)
       continue
     }
     const inspected = inspectIconBytes(bytes)
     if (!('contentType' in inspected)) {
-      skipped.push({ asset: source.asset, reason: inspected.rejected })
+      skip(source.asset, inspected.rejected)
       continue
     }
     if (inspected.contentType !== source.contentType) {
-      skipped.push({ asset: source.asset, reason: 'CONTENT_TYPE_CHANGED' })
+      skip(source.asset, 'CONTENT_TYPE_CHANGED')
       continue
     }
     if (byteDigest(bytes) !== source.digest || bytes.byteLength !== source.bytes) {
-      skipped.push({ asset: source.asset, reason: 'DIGEST_MISMATCH' })
+      skip(source.asset, 'DIGEST_MISMATCH')
       continue
     }
     await fs.mkdir(dirname(destination), { recursive: true })
-    await fs.writeFile(destination, bytes)
+    await writeFileAtomically(destination, bytes)
     staged.push(publishedAssetOf(source))
+    complete.add(source.asset)
+    skipped.delete(source.asset)
   }
   // Distinct assets: two products can share one mark, and the catalog declares
   // each asset once.
-  return { staged: dedupeAssets(staged), skipped }
+  return {
+    staged: dedupeAssets(staged),
+    skipped: [...skipped].map(([asset, reason]) => ({ asset, reason })),
+  }
 }
 
 function dedupeAssets(assets: readonly PublishedAsset[]): readonly PublishedAsset[] {
@@ -192,5 +205,5 @@ export async function stageIconBytes(
   const existing = await fs.readFile(destination).catch(() => undefined)
   if (existing && byteDigest(existing) === byteDigest(bytes)) return
   await fs.mkdir(dirname(destination), { recursive: true })
-  await fs.writeFile(destination, bytes)
+  await writeFileAtomically(destination, bytes)
 }

package/src/index.test.ts

@@ -1,4 +1,5 @@
 import { chmod, mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { execFileSync } from 'node:child_process'
 import { readdirSync, readFileSync } from 'node:fs'
 import { gzipSync } from 'node:zlib'
 import { pack } from 'tar-stream'
@@ -21,6 +22,7 @@ import {
   type CategoryMap,
   type ProductAliases,
   type ResolvedSource,
+  type GeneratedArtifacts,
 } from './index.js'
 import {
   parseJsonDocument,
@@ -466,6 +468,106 @@ describe('deterministic catalog synchronization', () => {
     }
   })
 
+  test.skipIf(process.platform === 'win32')(
+    'pins annotated and lightweight tags to the target commit',
+    async () => {
+      const root = await mkdtemp(join(tmpdir(), 'plugin-tag-pin-'))
+      const repo = join(root, 'repository')
+      const bin = join(root, 'bin')
+      const originalPath = process.env.PATH
+      const originalGit = process.env.ADEA_TEST_REAL_GIT
+      const originalRepo = process.env.ADEA_TEST_TAG_REPO
+      const originalFetch = globalThis.fetch
+      const realGit = execFileSync('which', ['git'], { encoding: 'utf8' }).trim()
+      const git = (...args: string[]) =>
+        execFileSync(realGit, ['-C', repo, ...args], { encoding: 'utf8' }).trim()
+      try {
+        await mkdir(repo)
+        await mkdir(bin)
+        git('init', '-q', '-b', 'main')
+        git(
+          '-c',
+          'user.name=Fixture',
+          '-c',
+          'user.email=fixture@example.invalid',
+          'commit',
+          '--allow-empty',
+          '-qm',
+          'fixture'
+        )
+        git(
+          '-c',
+          'user.name=Fixture',
+          '-c',
+          'user.email=fixture@example.invalid',
+          'tag',
+          '-a',
+          'annotated',
+          '-m',
+          'fixture'
+        )
+        git('tag', 'lightweight')
+        const commit = git('rev-parse', 'HEAD')
+        expect(git('rev-parse', 'refs/tags/annotated')).not.toBe(commit)
+        const sourceSha = '5'.repeat(40)
+        const source: SourceConfig = {
+          ...sources[0]!,
+          sourceId: 'tag-fixture',
+          repositoryUrl: 'https://github.com/acme/marketplace',
+          manifestPath: 'marketplace.json',
+        }
+        const script = join(bin, 'git')
+        await writeFile(
+          script,
+          `#!/bin/sh\nif [ "$2" = "${source.repositoryUrl}" ]; then\n  printf '%s\\t%s\\n' '${sourceSha}' "$3"\nelse\n  shift 2\n  exec "$ADEA_TEST_REAL_GIT" ls-remote "$ADEA_TEST_TAG_REPO" "$@"\nfi\n`
+        )
+        await chmod(script, 0o700)
+        process.env.ADEA_TEST_REAL_GIT = realGit
+        process.env.ADEA_TEST_TAG_REPO = repo
+        process.env.PATH = `${bin}:${originalPath ?? ''}`
+        for (const ref of ['refs/tags/annotated', 'refs/tags/lightweight', 'refs/heads/main']) {
+          const manifest = JSON.stringify({
+            plugins: [
+              {
+                name: 'remote',
+                source: { source: 'git', url: 'https://github.com/acme/remote-plugin', ref },
+              },
+            ],
+          })
+          globalThis.fetch = (async (_url: unknown) => new Response(manifest)) as typeof fetch
+          const loaded: string[] = []
+          const result = await synchronize({
+            sources: [source],
+            categoryMap,
+            productAliases,
+            policy,
+            mode: 'live',
+            snapshotLoader: {
+              load: async (_url, sha) => {
+                loaded.push(sha)
+                return {
+                  files: new Map([['plugin.json', new TextEncoder().encode('{"name":"Remote"}')]]),
+                  symlinks: [],
+                }
+              },
+            },
+          })
+          expect(result.lock?.sources[0]?.pluginPins[0]?.resolvedCommitSha).toBe(commit)
+          expect(loaded).toEqual([commit])
+        }
+      } finally {
+        globalThis.fetch = originalFetch
+        if (originalPath === undefined) delete process.env.PATH
+        else process.env.PATH = originalPath
+        if (originalGit === undefined) delete process.env.ADEA_TEST_REAL_GIT
+        else process.env.ADEA_TEST_REAL_GIT = originalGit
+        if (originalRepo === undefined) delete process.env.ADEA_TEST_TAG_REPO
+        else process.env.ADEA_TEST_TAG_REPO = originalRepo
+        await rm(root, { recursive: true, force: true })
+      }
+    }
+  )
+
   test.skipIf(process.platform === 'win32')(
     'refreshes floating external refs even when the marketplace head is unchanged',
     async () => {
@@ -602,6 +704,26 @@ describe('deterministic catalog synchronization', () => {
     verifyArtifacts(result.artifacts!)
   })
 
+  test('preserves an existing recovery directory when writing artifacts', async () => {
+    const parent = await mkdtemp(join(tmpdir(), 'plugin-recovery-'))
+    const output = join(parent, 'generated')
+    const backup = `${output}.previous`
+    try {
+      await mkdir(backup)
+      await writeFile(join(backup, 'keep.txt'), 'recover me')
+      const artifacts = { 'catalog.v1.json': '{}' } as unknown as GeneratedArtifacts
+      await expect(writeArtifacts(output, artifacts)).rejects.toThrow('CATALOG_RECOVERY_REQUIRED')
+      expect(await readFile(join(backup, 'keep.txt'), 'utf8')).toBe('recover me')
+      await mkdir(output)
+      await writeFile(join(output, 'current.txt'), 'current')
+      await expect(writeArtifacts(output, artifacts)).rejects.toThrow('CATALOG_RECOVERY_REQUIRED')
+      expect(await readFile(join(backup, 'keep.txt'), 'utf8')).toBe('recover me')
+      expect(await readFile(join(output, 'current.txt'), 'utf8')).toBe('current')
+    } finally {
+      await rm(parent, { recursive: true, force: true })
+    }
+  })
+
   test('keeps a failed build from producing a new artifact set', async () => {
     const first = await synchronize({
       sources,