@adea-ai/plugins 4.0.0 → 4.0.6

package/src/consumer-index.test.ts

@@ -101,7 +101,7 @@ describe('product placement', () => {
           categories: ['productivity'],
         }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.counts).toEqual({ plugins: 2, products: 1, redundantPlugins: 1 })
     expect(index.products['google-calendar']).toMatchObject({
@@ -121,7 +121,7 @@ describe('product placement', () => {
       plugin({ sourceId: 'claude-official', name: 'slack', categories: ['productivity'] }),
       plugin({ sourceId: 'openai-official', name: 'slack', categories: ['communication'] }),
     ])
-    const index = buildConsumerIndex({ catalog: base, preference })
+    const index = buildConsumerIndex({ catalog: base, productPreference: preference })
     // Sources disagree about where Slack belongs; the product belongs in both,
     // while the canonical variant still decides identity.
     expect(index.products.slack!.categories).toEqual(['communication', 'productivity'])
@@ -156,7 +156,7 @@ describe('product placement', () => {
         { ...first, currentReleaseId: 'release:same' },
         { ...second, currentReleaseId: 'release:same' },
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(identical.products.atlan!.variantsIdentical).toBe(true)
   })
@@ -172,18 +172,57 @@ describe('product placement', () => {
           releaseRepositoryUrl: 'https://github.com/slackapi/slack-mcp-plugin',
         }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.slack!.pluginId).toBe('plugin:openai-official:slack')
   })
 
+  test('selects the canonical variant using the current release rather than an earlier release', () => {
+    const wrapper = plugin({
+      sourceId: 'claude-official',
+      name: 'slack',
+      categories: ['communication'],
+    })
+    const candidate = plugin({
+      sourceId: 'openai-official',
+      name: 'slack',
+      categories: ['communication'],
+      releaseRepositoryUrl: 'https://github.com/slackapi/slack-mcp-plugin',
+    })
+    const current = candidate.availableReleases[0]!
+    const oldWrapper = {
+      ...current,
+      releaseId: 'release:old-wrapper',
+      resolvedRepositoryUrl: 'https://github.com/openai-official/marketplace',
+    }
+    const vendorNow = { ...candidate, availableReleases: [oldWrapper, current] }
+    const vendorIndex = buildConsumerIndex({
+      catalog: catalog([wrapper, vendorNow]),
+      productPreference: preference,
+    })
+    expect(vendorIndex.products.slack!.pluginId).toBe(candidate.pluginId)
+    expect(vendorIndex.products.slack!.release.releaseId).toBe(current.releaseId)
+
+    const currentWrapper = {
+      ...current,
+      resolvedRepositoryUrl: 'https://github.com/openai-official/marketplace',
+    }
+    const oldVendor = { ...current, releaseId: 'release:old-vendor' }
+    const wrapperNow = { ...candidate, availableReleases: [oldVendor, currentWrapper] }
+    const wrapperIndex = buildConsumerIndex({
+      catalog: catalog([wrapper, wrapperNow]),
+      productPreference: preference,
+    })
+    expect(wrapperIndex.products.slack!.pluginId).toBe(wrapper.pluginId)
+  })
+
   test('falls back to the configured source order when every variant is a wrapper', () => {
     const index = buildConsumerIndex({
       catalog: catalog([
         plugin({ sourceId: 'openai-official', name: 'github', categories: ['developer-tools'] }),
         plugin({ sourceId: 'claude-official', name: 'github', categories: ['developer-tools'] }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.github!.pluginId).toBe('plugin:claude-official:github')
   })
@@ -194,7 +233,7 @@ describe('product placement', () => {
         plugin({ sourceId: 'claude-official', name: 'github', categories: ['developer-tools'] }),
         plugin({ sourceId: 'cursor-official', name: 'github', categories: ['developer-tools'] }),
       ]),
-      preference: {
+      productPreference: {
         ...preference,
         canonicalOverrides: { github: 'plugin:cursor-official:github' },
       },
@@ -213,7 +252,7 @@ describe('product placement', () => {
           displayName: 'Figma',
         }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.figma!.displayName).toBe('Figma')
     expect(index.products.figma!.pluginId).toBe('plugin:claude-official:figma')
@@ -224,7 +263,7 @@ describe('product placement', () => {
       catalog: catalog([
         plugin({ sourceId: 'unlisted-source', name: 'tool', categories: ['developer-tools'] }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.tool!.pluginId).toBe('plugin:unlisted-source:tool')
   })
@@ -233,6 +272,31 @@ describe('product placement', () => {
 describe('category shelves', () => {
   const names = ['alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta', 'eta']
 
+  test('rejects invalid shelf limits while allowing an empty shelf', () => {
+    const input = {
+      catalog: catalog(
+        names.map((name) =>
+          plugin({ sourceId: 'claude-official', name, categories: ['productivity'] })
+        )
+      ),
+      productPreference: preference,
+    }
+    expect(buildConsumerIndex({ ...input, topCount: 0 }).categories[0]!.topProductKeys).toEqual([])
+    for (const topCount of [
+      -1,
+      1.5,
+      Number.NaN,
+      Infinity,
+      Number.MAX_SAFE_INTEGER + 1,
+      null,
+      '3',
+    ]) {
+      expect(() => buildConsumerIndex({ ...input, topCount: topCount as number })).toThrow(
+        'TOP_COUNT_INVALID'
+      )
+    }
+  })
+
   test('orders curated products first and fills the rest deterministically', () => {
     const index = buildConsumerIndex({
       catalog: catalog(
@@ -242,7 +306,7 @@ describe('category shelves', () => {
       ),
       leading: { productivity: ['zeta', 'gamma'] },
       topCount: 4,
-      preference,
+      productPreference: preference,
     })
     const category = index.categories[0]!
     expect(category.productKeys).toEqual([
@@ -270,7 +334,7 @@ describe('category shelves', () => {
         }),
       ]),
       leading: { 'education-research': ['teaching'] },
-      preference,
+      productPreference: preference,
     })
     expect(
       index.categories.find((item) => item.category === 'developer-tools')!.topProductKeys
@@ -296,7 +360,7 @@ describe('category shelves', () => {
         security: ['nightvision', 'no-such-plugin'],
         'unknown-category': ['anything'],
       },
-      preference,
+      productPreference: preference,
     })
     expect(index.diagnostics).toEqual([
       { category: 'developer-tools', name: 'getsentry', reason: 'PRODUCT_NOT_FOUND' },
@@ -309,6 +373,73 @@ describe('category shelves', () => {
     expect(developer.topProductKeys).toEqual(['sentry', 'nightvision'])
   })
 
+  test('reports aliases outside the category and ambiguous curated names', () => {
+    const plugins = [
+      plugin({
+        sourceId: 'source-one',
+        name: 'shared',
+        categories: ['tools'],
+        productGroupingKey: 'first-product',
+      }),
+      plugin({
+        sourceId: 'source-two',
+        name: 'shared',
+        categories: ['tools'],
+        productGroupingKey: 'second-product',
+      }),
+      plugin({
+        sourceId: 'source-one',
+        name: 'renamed',
+        categories: ['other'],
+        productGroupingKey: 'actual-product',
+      }),
+      plugin({ sourceId: 'source-one', name: 'present', categories: ['tools'] }),
+    ]
+    for (const entries of [plugins, plugins.toReversed()]) {
+      const index = buildConsumerIndex({
+        catalog: catalog(entries),
+        leading: { tools: ['shared', 'renamed', 'present'] },
+        productPreference: preference,
+      })
+      expect(index.diagnostics).toEqual([
+        { category: 'tools', name: 'renamed', reason: 'PRODUCT_NOT_IN_CATEGORY' },
+        { category: 'tools', name: 'shared', reason: 'PRODUCT_AMBIGUOUS' },
+      ])
+      expect(index.categories.find((item) => item.category === 'tools')!.productKeys[0]).toBe(
+        'present'
+      )
+    }
+  })
+
+  test('curates a product when a differently named variant belongs to the category', () => {
+    const plugins = [
+      plugin({
+        sourceId: 'source-one',
+        name: 'named',
+        categories: ['other'],
+        productGroupingKey: 'shared-product',
+      }),
+      plugin({
+        sourceId: 'source-two',
+        name: 'alternate',
+        categories: ['tools'],
+        productGroupingKey: 'shared-product',
+      }),
+      plugin({ sourceId: 'source-one', name: 'alpha', categories: ['tools'] }),
+    ]
+    for (const entries of [plugins, plugins.toReversed()]) {
+      const index = buildConsumerIndex({
+        catalog: catalog(entries),
+        leading: { tools: ['named'] },
+        productPreference: preference,
+      })
+      expect(index.diagnostics).toEqual([])
+      expect(index.categories.find((item) => item.category === 'tools')!.topProductKeys[0]).toBe(
+        'shared-product'
+      )
+    }
+  })
+
   test('is deterministic for the same catalog in any input order', () => {
     const forward = names
       .slice(0, 3)
@@ -316,12 +447,12 @@ describe('category shelves', () => {
     const first = buildConsumerIndex({
       catalog: catalog(forward),
       leading: { productivity: ['gamma'] },
-      preference,
+      productPreference: preference,
     })
     const second = buildConsumerIndex({
       catalog: catalog(forward.toReversed()),
       leading: { productivity: ['gamma'] },
-      preference,
+      productPreference: preference,
     })
     expect(JSON.stringify(first)).toBe(JSON.stringify(second))
   })
@@ -402,7 +533,7 @@ describe('consumer index verification', () => {
     const index = buildConsumerIndex({
       catalog: base,
       leading: { productivity: ['b'] },
-      preference,
+      productPreference: preference,
     })
     const result = verifyConsumerIndex(JSON.stringify(index), base)
     expect(result.hasConsumerIndex).toBe(true)
@@ -429,7 +560,7 @@ describe('consumer index verification', () => {
 
   test('rejects a category list that names a plugin outside the catalog', () => {
     const base = catalog(plugins)
-    const index = buildConsumerIndex({ catalog: base, preference })
+    const index = buildConsumerIndex({ catalog: base, productPreference: preference })
     const tampered = {
       ...index,
       categories: index.categories.map((category) => ({
@@ -450,7 +581,7 @@ describe('consumer index verification', () => {
         categories: ['productivity', 'communication'],
       }),
     ])
-    const index = buildConsumerIndex({ catalog: base, preference })
+    const index = buildConsumerIndex({ catalog: base, productPreference: preference })
     const tampered = {
       ...index,
       categories: index.categories.map((category) => ({

package/src/consumer-index.ts

@@ -1,4 +1,5 @@
 import type { Catalog, Plugin, PluginRelease } from './schema.js'
+import { PACKAGE_METADATA_KEY } from './agent-plugins-schema.js'
 import { iconAssetName, type IconContentType } from './icons.js'
 import { immutableAssetUrl } from './publication.js'
 
@@ -60,7 +61,7 @@ export function parseProductPreference(input: unknown): ProductPreference {
 export interface ProductIcon {
   /** `content` is the vendor's own plugin file; `favicon` is the product site's. */
   readonly kind: 'content' | 'favicon'
-  /** Release asset name; fetch it from the release for this `catalogId`. */
+  /** Content-addressed asset name, published beside the catalog's artifacts. */
   readonly asset: string
   /**
    * Absolute, immutable URL for the asset, present when the build knows where
@@ -111,29 +112,6 @@ export interface ConsumerRelease {
   readonly packageDigest?: string
 }
 
-/** One installable product, resolved from every source variant that publishes it. */ /**
- * The install-relevant facts of the release a product installs.
- *
- * A browsing client shows a plugin, then plans an install from it: the digest it
- * must pin, the connectors and credentials setup will ask for, and the
- * capabilities the harness has to negotiate. Carrying them here means the grid
- * needs no second artifact.
- */
-export interface ConsumerRelease {
-  readonly releaseId: string
-  readonly canonicalContentDigest: string
-  readonly contentResolution: string
-  readonly capabilities: readonly { readonly type: string; readonly name: string }[]
-  readonly requiredConnectors: readonly string[]
-  readonly requiredCredentials: readonly string[]
-  /** Commit the release was resolved from, for audit and update state. */
-  readonly sourceRevision: string
-  readonly upstreamVersion?: string
-  /** Canonical package status, when the release carries one. */
-  readonly packageStatus?: string
-  readonly packageDigest?: string
-}
-
 /** One installable product, resolved from every source variant that publishes it. */
 export interface ConsumerProduct {
   readonly productKey: string
@@ -194,7 +172,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 +239,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(
@@ -315,7 +297,9 @@ function nestedString(value: unknown, key: string): string | undefined {
 
 function describeRelease(plugin: Plugin): ConsumerRelease {
   const release = currentRelease(plugin)!
-  const packages = ((release.releaseMetadata ?? {}) as Record<string, unknown>).agentPlugins
+  const packages = release.releaseMetadata[PACKAGE_METADATA_KEY]
+  const packageStatus = nestedString(packages, 'status')
+  const packageDigest = nestedString(packages, 'packageDigest')
   return {
     releaseId: release.releaseId,
     canonicalContentDigest: release.canonicalContentDigest,
@@ -328,12 +312,8 @@ function describeRelease(plugin: Plugin): ConsumerRelease {
     requiredCredentials: [...release.requiredCredentials],
     sourceRevision: release.resolvedCommitSha,
     ...(release.upstreamVersion ? { upstreamVersion: release.upstreamVersion } : {}),
-    ...(nestedString(packages, 'status')
-      ? { packageStatus: nestedString(packages, 'status')! }
-      : {}),
-    ...(nestedString(packages, 'packageDigest')
-      ? { packageDigest: nestedString(packages, 'packageDigest')! }
-      : {}),
+    ...(packageStatus ? { packageStatus } : {}),
+    ...(packageDigest ? { packageDigest } : {}),
   }
 }
 
@@ -403,21 +383,23 @@ function compactCompatibility(plugin: Plugin): Record<string, string> {
  * stable identifiers.
  */
 export function buildConsumerIndex(input: {
-  readonly catalog: Pick<Catalog, 'plugins' | 'sources'>
+  /** A catalog without its ID yields records with no published asset URLs. */
+  readonly catalog: Pick<Catalog, 'plugins' | 'sources'> & { readonly catalogId?: string }
   readonly leading?: Readonly<Record<string, readonly string[]>>
   readonly topCount?: number
-  readonly preference?: ProductPreference
+  readonly productPreference?: ProductPreference
   /** Where the catalog will be published, so records can carry absolute URLs. */
   readonly publicationRepositoryUrl?: string
   /** Committed asset base a browser can fetch directly; preferred when set. */
   readonly publicationAssetsBaseUrl?: string
 }): ConsumerIndex {
-  const preference = input.preference ?? {
+  const preference = input.productPreference ?? {
     schemaVersion: 1 as const,
     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])
   )
@@ -427,7 +409,7 @@ export function buildConsumerIndex(input: {
     if (list) list.push(plugin)
     else variantsByProduct.set(plugin.productGroupingKey, [plugin])
   }
-  const catalogId = (input.catalog as { catalogId?: string }).catalogId ?? ''
+  const catalogId = input.catalog.catalogId ?? ''
   const products: Record<string, ConsumerProduct> = {}
   for (const [productKey, variants] of [...variantsByProduct].toSorted((left, right) =>
     left[0].localeCompare(right[0])
@@ -503,18 +485,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/digest.ts

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto'
+
+const DIGEST_PREFIX = 'sha256:'
+
+function sha256Hex(data: string | Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+/** Ordinal (UTF-16 code unit) order: the same on every machine and locale. */
+export function ordinalCompare(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+export 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(',')}}`
+}
+
+/** Digest of a JSON value's canonical form, in the catalog's digest format. */
+export function digest(value: unknown): string {
+  return `${DIGEST_PREFIX}${sha256Hex(canonicalJson(value))}`
+}
+
+/** Digest of one byte buffer (a string is hashed as UTF-8), in the catalog's digest format. */
+export function byteDigest(bytes: string | Uint8Array): string {
+  return `${DIGEST_PREFIX}${sha256Hex(bytes)}`
+}
+
+/** Shared source-byte identity for catalog provenance and canonical package recipes. */
+export function sourceDigest(files: ReadonlyMap<string, Uint8Array>): string {
+  const hash = createHash('sha256')
+  // English matches the compiler runtime; ordinal ties distinguish equivalent Unicode names.
+  for (const [path, bytes] of [...files].toSorted(
+    ([a], [b]) => a.localeCompare(b, 'en') || ordinalCompare(a, b)
+  )) {
+    hash.update(`${path.length}:${path}:${bytes.byteLength}:`)
+    hash.update(bytes)
+  }
+  return `${DIGEST_PREFIX}${hash.digest('hex')}`
+}
+
+/** A content-addressed identifier such as `catalog:<hex>` for a JSON body. */
+export function contentId(prefix: string, body: unknown): string {
+  return `${prefix}:${sha256Hex(canonicalJson(body))}`
+}
+
+/** The hex part of a `sha256:<hex>` digest. */
+export function digestHex(value: string): string {
+  return value.startsWith(DIGEST_PREFIX) ? value.slice(DIGEST_PREFIX.length) : value
+}

package/src/fs-atomic.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+/** Creates `path`, failing if it exists, and syncs the bytes before returning. */
+export async function writeDurably(path: string, content: string | Uint8Array): Promise<void> {
+  const handle = await fs.open(path, 'wx')
+  try {
+    await handle.writeFile(content)
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/**
+ * Writes one file so a reader sees either the old or the new bytes. For
+ * content-addressed assets and the browsing index beside the catalog.
+ */
+export async function writeFileAtomically(
+  path: string,
+  content: string | Uint8Array
+): Promise<void> {
+  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`)
+  try {
+    await writeDurably(temporary, content)
+    await fs.rename(temporary, path)
+  } catch (error) {
+    await fs.rm(temporary, { force: true })
+    throw error
+  }
+}