@adea-ai/plugins 4.0.0 → 4.0.6

package/src/source-resolution.ts

@@ -0,0 +1,233 @@
+import { promises as fs } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { mapWithConcurrency } from './concurrency.js'
+import { contentId, digest, ordinalCompare } from './digest.js'
+import { SourcesLockSchema, type SourceLockEntry, type SourcesLock } from './schema.js'
+import {
+  canonicalRepositoryUrl,
+  parseJsonDocument,
+  parseMarketplaceManifest,
+  safeRelativePath,
+  type ParsedMarketplace,
+  type PluginSourceSpec,
+  type SourceConfig,
+} from './sources.js'
+import { externalGitRef, fetchText, rawContentUrl, resolveGitRef } from './upstream.js'
+
+export interface ResolvedSource {
+  readonly config: SourceConfig
+  readonly commitSha: string
+  readonly manifestText: string
+  readonly parsed: ParsedMarketplace
+  readonly pluginPins: readonly PluginSourcePin[]
+  readonly retrievedAt: string
+  readonly manifestDigest: string
+}
+
+export interface PluginSourcePin {
+  readonly pluginName: string
+  readonly repositoryUrl: string
+  readonly pluginSubdirectory: string
+  readonly resolvedCommitSha: string
+}
+
+export async function resolvePluginSource(
+  pluginName: string,
+  spec: PluginSourceSpec,
+  source: ResolvedSource,
+  resolveExternalRefs: boolean
+): Promise<ResolvedPluginSource> {
+  if (spec.kind === 'local')
+    return {
+      repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
+      subdirectory: spec.path,
+      commitSha: source.commitSha,
+    }
+  const canonicalUrl = canonicalRepositoryUrl(spec.repositoryUrl)
+  const pin = source.pluginPins.find(
+    (candidate) =>
+      candidate.pluginName === pluginName &&
+      candidate.repositoryUrl === canonicalUrl &&
+      candidate.pluginSubdirectory === spec.subdirectory
+  )
+  const commitSha =
+    pin?.resolvedCommitSha ??
+    spec.sha ??
+    (resolveExternalRefs
+      ? await resolveGitRef(spec.repositoryUrl, externalGitRef(spec.ref))
+      : source.commitSha)
+  return {
+    repositoryUrl: canonicalUrl,
+    subdirectory: pin?.pluginSubdirectory ?? spec.subdirectory,
+    commitSha,
+  }
+}
+
+export interface ResolvedPluginSource {
+  readonly repositoryUrl: string
+  readonly subdirectory: string
+  readonly commitSha: string
+}
+
+/** The fields that differ between two lock entries for the same source. */
+export function lockChangedFields(previous: SourceLockEntry, current: SourceLockEntry): string[] {
+  const fields = [
+    'repositoryUrl',
+    'defaultBranch',
+    'manifestPath',
+    'marketplaceDialect',
+    'resolvedCommitSha',
+    'sourceManifestDigest',
+    'synchronizationStatus',
+  ] as const
+  const changed: string[] = fields.filter((field) => previous[field] !== current[field])
+  if (digest(sortedPins(previous)) !== digest(sortedPins(current))) changed.push('pluginPins')
+  return changed
+}
+
+export function sourceLockChanged(previous: SourceLockEntry, current: SourceLockEntry): boolean {
+  return lockChangedFields(previous, current).length > 0
+}
+
+function sortedPins(source: SourceLockEntry): string[] {
+  return source.pluginPins
+    .map((pin) =>
+      JSON.stringify([
+        pin.pluginName,
+        pin.repositoryUrl,
+        pin.pluginSubdirectory,
+        pin.resolvedCommitSha,
+      ])
+    )
+    .toSorted()
+}
+
+export function createSourcesLock(sources: readonly ResolvedSource[]): SourcesLock {
+  const entries: SourceLockEntry[] = sources
+    .map((source) => ({
+      sourceId: source.config.sourceId,
+      repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
+      defaultBranch: source.config.defaultBranch,
+      resolvedCommitSha: source.commitSha,
+      manifestPath: source.config.manifestPath,
+      marketplaceDialect: source.config.marketplaceDialect,
+      sourceManifestDigest: source.manifestDigest,
+      retrievedAt: source.retrievedAt,
+      synchronizationStatus: 'synchronized' as const,
+      pluginPins: source.pluginPins.map((pin) => ({ ...pin })),
+    }))
+    .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId))
+  const body = { schemaVersion: 1 as const, sources: entries }
+  return SourcesLockSchema.parse({
+    ...body,
+    lockId: contentId('lock', body),
+  })
+}
+
+export async function resolveSource(
+  config: SourceConfig,
+  mode: 'live' | 'offline',
+  fixtureRoot: string | undefined,
+  lock: SourcesLock | undefined,
+  fromLock: boolean
+): Promise<ResolvedSource> {
+  const manifestPath = safeRelativePath(config.manifestPath, 'SOURCE_MANIFEST_PATH_INVALID')
+  const locked = lock?.sources.find((entry) => entry.sourceId === config.sourceId)
+  if (fromLock && !locked) throw new Error(`SOURCE_LOCK_ENTRY_MISSING: ${config.sourceId}`)
+  const commitSha =
+    fromLock && locked
+      ? locked.resolvedCommitSha
+      : mode === 'offline'
+        ? (config.fixtureCommitSha ?? locked?.resolvedCommitSha)
+        : await resolveGitRef(config.repositoryUrl, `refs/heads/${config.defaultBranch}`)
+  if (!commitSha || !/^[a-f0-9]{40}$/.test(commitSha))
+    throw new Error(`SOURCE_COMMIT_UNRESOLVED: ${config.sourceId}`)
+  const manifestText =
+    mode === 'offline'
+      ? await readFixtureManifest({ ...config, manifestPath }, fixtureRoot)
+      : await fetchText(rawContentUrl(config.repositoryUrl, commitSha, manifestPath))
+  const parsed = parseMarketplaceManifest(parseJsonDocument(manifestText), config)
+  if (fromLock && locked && digest(manifestText) !== locked.sourceManifestDigest)
+    throw new Error(`SOURCE_LOCK_MANIFEST_MISMATCH: ${config.sourceId}`)
+  const pluginPins = await resolvePluginPins({
+    config,
+    parsed,
+    sourceCommitSha: commitSha,
+    lockedPins: locked?.pluginPins,
+    fromLock,
+    resolveExternalRefs: mode === 'live',
+  })
+  return {
+    config,
+    commitSha,
+    manifestText,
+    parsed,
+    pluginPins,
+    retrievedAt:
+      fromLock && locked
+        ? locked.retrievedAt
+        : mode === 'offline'
+          ? '2026-01-01T00:00:00.000Z'
+          : new Date().toISOString(),
+    manifestDigest: digest(manifestText),
+  }
+}
+
+async function resolvePluginPins(input: {
+  readonly config: SourceConfig
+  readonly parsed: ParsedMarketplace
+  readonly sourceCommitSha: string
+  readonly lockedPins: readonly PluginSourcePin[] | undefined
+  readonly fromLock: boolean
+  readonly resolveExternalRefs: boolean
+}): Promise<PluginSourcePin[]> {
+  const pins = await mapWithConcurrency(
+    input.parsed.entries,
+    8,
+    async (entry): Promise<PluginSourcePin> => {
+      if (entry.source.kind === 'local') {
+        return {
+          pluginName: entry.name,
+          repositoryUrl: canonicalRepositoryUrl(input.config.repositoryUrl),
+          pluginSubdirectory: entry.source.path,
+          resolvedCommitSha: input.sourceCommitSha,
+        }
+      }
+
+      const repositoryUrl = canonicalRepositoryUrl(entry.source.repositoryUrl)
+      const pluginSubdirectory = entry.source.subdirectory
+      // 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) {
+        if (
+          locked.repositoryUrl !== repositoryUrl ||
+          locked.pluginSubdirectory !== pluginSubdirectory
+        ) {
+          throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISMATCH: ${input.config.sourceId}:${entry.name}`)
+        }
+        return locked
+      }
+
+      const resolvedCommitSha =
+        entry.source.sha ??
+        (input.resolveExternalRefs
+          ? await resolveGitRef(repositoryUrl, externalGitRef(entry.source.ref))
+          : input.sourceCommitSha)
+      return { pluginName: entry.name, repositoryUrl, pluginSubdirectory, resolvedCommitSha }
+    }
+  )
+  return pins.toSorted((left, right) => ordinalCompare(left.pluginName, right.pluginName))
+}
+
+async function readFixtureManifest(
+  config: SourceConfig,
+  fixtureRoot: string | undefined
+): Promise<string> {
+  if (!fixtureRoot || !config.fixturePath)
+    throw new Error(`FIXTURE_ROOT_REQUIRED: ${config.sourceId}`)
+  return fs.readFile(join(resolve(fixtureRoot), config.fixturePath, config.manifestPath), 'utf8')
+}

package/src/sources-json.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { parseJsonDocument } from './sources.js'
+import { parseJsonDocument, parseMarketplaceManifest, type SourceConfig } from './sources.js'
 
 describe('JSON document whitespace', () => {
   test('accepts the four JSON whitespace characters around nested values', () => {
@@ -19,7 +19,6 @@ describe('JSON document whitespace', () => {
         `[1${space},2]`,
         `[1,${space}2]`,
       ]) {
-        expect(() => JSON.parse(text)).toThrow()
         expect(() => parseJsonDocument(text)).toThrow('JSON_MALFORMED')
       }
     }
@@ -34,3 +33,20 @@ describe('JSON document whitespace', () => {
     expect(() => parseJsonDocument('{"name":1,"na\\u006de":2}')).toThrow('JSON_DUPLICATE_KEY')
   })
 })
+
+test('sorts marketplace metadata independently of the host locale', () => {
+  const source: SourceConfig = {
+    sourceId: 'test',
+    displayName: 'Test',
+    repositoryUrl: 'https://github.com/example/plugins',
+    marketplaceDialect: 'openai',
+    manifestPath: 'marketplace.json',
+    defaultBranch: 'main',
+    trustClassification: 'official',
+  }
+  const parsed = parseMarketplaceManifest(
+    { plugins: [{ name: 'test', source: './test', keywords: ['ä', 'z', 'a', 'ä'] }] },
+    source
+  )
+  expect(parsed.entries[0]?.keywords).toEqual(['a', 'z', 'ä'])
+})

package/src/sources.ts

@@ -1,6 +1,9 @@
-import { createHash } from 'node:crypto'
+import { digest, ordinalCompare } from './digest.js'
+import { isString, stringValue } from './json-values.js'
+import type { MarketplaceDialectSchema } from './schema.js'
+import type { z } from 'zod'
 
-export type MarketplaceDialect = 'openai' | 'cursor' | 'claude'
+export type MarketplaceDialect = z.output<typeof MarketplaceDialectSchema>
 
 export interface SourceConfig {
   readonly sourceId: string
@@ -44,6 +47,8 @@ export interface ParsedMarketplace {
   readonly marketplaceDescription: string
   readonly owner: readonly string[]
   readonly entries: readonly MarketplacePluginEntry[]
+  /** Entries left out because their source kind cannot be installed from a repository. */
+  readonly unsupportedEntries?: readonly string[]
   readonly raw: Record<string, unknown>
 }
 
@@ -62,7 +67,23 @@ export function parseMarketplaceManifest(input: unknown, source: SourceConfig):
   const plugins = root.plugins
   if (!Array.isArray(plugins)) throw new SourceAdapterError('MARKETPLACE_PLUGINS_REQUIRED')
 
-  const entries = plugins.map((value, index) => parsePluginEntry(value, source, index))
+  // Upstream marketplaces can list plugins that install some other way, such as by running a
+  // command. Those stay out of the catalog, and they must not stop the rest of it from building.
+  const entries: MarketplacePluginEntry[] = []
+  const unsupportedEntries: string[] = []
+  for (const [index, value] of plugins.entries()) {
+    try {
+      entries.push(parsePluginEntry(value, source, index))
+    } catch (error) {
+      if (!(error instanceof SourceAdapterError) || error.code !== 'PLUGIN_SOURCE_KIND_UNSUPPORTED')
+        throw error
+      unsupportedEntries.push(error.details.join(': '))
+    }
+  }
+  if (unsupportedEntries.length > 0)
+    console.error(
+      `${source.sourceId}: left out plugins with unsupported source kinds: ${unsupportedEntries.join(', ')}`
+    )
   const duplicateNames = new Set<string>()
   for (const entry of entries) {
     if (duplicateNames.has(entry.name))
@@ -72,8 +93,9 @@ export function parseMarketplaceManifest(input: unknown, source: SourceConfig):
   return {
     marketplaceName: stringValue(root.name) ?? source.displayName,
     marketplaceDescription: stringValue(root.description) ?? '',
-    owner: ownerNames(root.owner),
+    owner: authorNames(root.owner),
     entries,
+    ...(unsupportedEntries.length > 0 ? { unsupportedEntries } : {}),
     raw: root,
   }
 }
@@ -302,18 +324,8 @@ function requiredString(input: unknown, code: string, detail: string): string {
   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)
-  )
+  return [...new Set(input.map((value) => value.trim()).filter(Boolean))].toSorted(ordinalCompare)
 }
 
 function authorNames(input: unknown): string[] {
@@ -327,10 +339,6 @@ function authorNames(input: unknown): string[] {
   return []
 }
 
-function ownerNames(input: unknown): string[] {
-  return authorNames(input)
-}
-
 function safeOptionalUrl(input: unknown): string | undefined {
   if (!isString(input)) return undefined
   try {
@@ -344,17 +352,3 @@ function safeOptionalUrl(input: unknown): string | 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(',')}}`
-}

package/src/synchronize.ts

@@ -0,0 +1,213 @@
+import { createArtifacts, type ConsumerIndexOptions, type GeneratedArtifacts } from './artifacts.js'
+import { buildCatalogInternal, type BuildCatalogInput } from './build.js'
+import { mapWithConcurrency } from './concurrency.js'
+import { digest } from './digest.js'
+import type { SkippedPlugin } from './plugin-skips.js'
+import type { CatalogPolicy } from './policy.js'
+import type { Catalog, CatalogSource, SourceLockEntry, SourcesLock } from './schema.js'
+import { FixtureSnapshotLoader, NetworkSnapshotLoader, type SnapshotLoader } from './snapshots.js'
+import { createSourcesLock, resolveSource, sourceLockChanged } from './source-resolution.js'
+import type { SourceConfig } from './sources.js'
+import { verifyArtifacts } from './verify-artifacts.js'
+
+export interface SyncInput
+  extends
+    ConsumerIndexOptions,
+    Omit<BuildCatalogInput, 'resolvedSources' | 'snapshotLoader' | 'resolveExternalRefs'> {
+  readonly sources: readonly SourceConfig[]
+  readonly policy: CatalogPolicy
+  readonly mode?: 'live' | 'offline'
+  readonly fixtureRoot?: string
+  readonly sourceId?: string
+  readonly dryRun?: boolean
+  readonly existingLock?: SourcesLock
+  readonly existingCatalog?: Catalog
+  readonly fromLock?: SourcesLock
+  readonly snapshotLoader?: SnapshotLoader
+  /** Rebuild even when source pins are unchanged (used for explicit format migrations). */
+  readonly forceRebuild?: boolean
+}
+
+export interface SyncResult {
+  readonly changed: boolean
+  readonly dryRun: boolean
+  readonly sourceHeads: readonly { sourceId: string; commitSha: string }[]
+  readonly catalog?: Catalog
+  readonly lock?: SourcesLock
+  readonly artifacts?: GeneratedArtifacts
+  readonly changeReport: ChangeReport
+}
+
+export interface ChangeReport {
+  readonly schemaVersion: 1
+  readonly changedSources: readonly string[]
+  readonly addedPlugins: readonly string[]
+  readonly removedPlugins: readonly string[]
+  readonly changedPlugins: readonly string[]
+  readonly permissionSensitiveChanges: readonly string[]
+  readonly skippedPlugins: readonly SkippedPlugin[]
+  readonly contentResolution: 'complete' | 'complete-with-skips' | 'metadata-only'
+}
+
+export async function synchronize(input: SyncInput): Promise<SyncResult> {
+  const mode = input.mode ?? 'live'
+  const configs = input.sources.filter(
+    (source) => !input.sourceId || source.sourceId === input.sourceId
+  )
+  if (configs.length === 0) throw new Error(`SOURCE_NOT_FOUND: ${input.sourceId ?? 'none'}`)
+  const lockToUse = input.fromLock ?? input.existingLock
+  const resolved = await mapWithConcurrency(configs, 4, (config) =>
+    resolveSource(config, mode, input.fixtureRoot, lockToUse, input.fromLock !== undefined)
+  )
+  const sourceHeads = resolved.map(({ config, commitSha }) => ({
+    sourceId: config.sourceId,
+    commitSha,
+  }))
+  const lock = createSourcesLock(resolved)
+  const unchanged =
+    input.fromLock === undefined &&
+    input.forceRebuild !== true &&
+    input.existingLock !== undefined &&
+    resolved.length === input.existingLock.sources.length &&
+    lock.sources.every(
+      (source) =>
+        !sourceChanged(
+          source,
+          resolved.find((entry) => entry.config.sourceId === source.sourceId)?.config,
+          input.existingLock,
+          input.existingCatalog
+        )
+    )
+  if (unchanged) {
+    return {
+      changed: false,
+      dryRun: input.dryRun ?? false,
+      sourceHeads,
+      changeReport: {
+        schemaVersion: 1,
+        changedSources: [],
+        addedPlugins: [],
+        removedPlugins: [],
+        changedPlugins: [],
+        permissionSensitiveChanges: [],
+        skippedPlugins: [],
+        contentResolution: input.metadataOnly ? 'metadata-only' : 'complete',
+      },
+    }
+  }
+
+  const { catalog, skippedPlugins } = await buildCatalogInternal({
+    ...input,
+    resolvedSources: resolved,
+    snapshotLoader:
+      input.snapshotLoader ??
+      (mode === 'offline'
+        ? new FixtureSnapshotLoader(input.fixtureRoot ?? 'fixtures', configs)
+        : new NetworkSnapshotLoader(input.policy)),
+    resolveExternalRefs: mode === 'live',
+  })
+  // An offline build replays fixtures, so its curation findings are noise.
+  const artifacts = createArtifacts(catalog, lock, {
+    ...input,
+    curationDiagnostics: mode !== 'offline',
+  })
+  verifyArtifacts(artifacts)
+  const report = createChangeReport(
+    catalog,
+    lock,
+    input.existingLock,
+    input.existingCatalog,
+    skippedPlugins
+  )
+  if (input.policy.publishRequiresCompleteContent && input.metadataOnly) {
+    throw new Error('CATALOG_CONTENT_INCOMPLETE: publication requires complete content')
+  }
+  return {
+    changed: true,
+    dryRun: input.dryRun ?? false,
+    sourceHeads,
+    catalog,
+    lock,
+    artifacts,
+    changeReport: report,
+  }
+}
+
+/** Whether a source differs from the last published lock and catalog. */
+function sourceChanged(
+  source: SourceLockEntry,
+  current: Pick<CatalogSource, 'displayName' | 'trustClassification'> | undefined,
+  existingLock: SourcesLock | undefined,
+  existingCatalog: Catalog | undefined
+): boolean {
+  const previous = existingLock?.sources.find((entry) => entry.sourceId === source.sourceId)
+  if (!previous || sourceLockChanged(previous, source)) return true
+  if (!existingCatalog) return false
+  const prior = existingCatalog.sources.find((entry) => entry.sourceId === source.sourceId)
+  return (
+    !prior ||
+    !current ||
+    prior.displayName !== current.displayName ||
+    prior.trustClassification !== current.trustClassification
+  )
+}
+
+function createChangeReport(
+  catalog: Catalog,
+  lock: SourcesLock,
+  existingLock?: SourcesLock,
+  existingCatalog?: Catalog,
+  skippedPlugins: readonly SkippedPlugin[] = []
+): ChangeReport {
+  const changedSources = lock.sources
+    .filter(
+      (source) =>
+        existingLock === undefined ||
+        sourceChanged(
+          source,
+          catalog.sources.find((entry) => entry.sourceId === source.sourceId),
+          existingLock,
+          existingCatalog
+        )
+    )
+    .map((source) => source.sourceId)
+  const previousPlugins = new Map(
+    existingCatalog?.plugins.map((plugin) => [plugin.pluginId, plugin]) ?? []
+  )
+  const currentPlugins = new Map(catalog.plugins.map((plugin) => [plugin.pluginId, plugin]))
+  const addedPlugins = catalog.plugins
+    .filter((plugin) => !previousPlugins.has(plugin.pluginId))
+    .map((plugin) => plugin.pluginId)
+  const removedPlugins = [...previousPlugins.keys()].filter(
+    (pluginId) => !currentPlugins.has(pluginId)
+  )
+  const changedPlugins = catalog.plugins
+    .filter((plugin) => {
+      const previous = previousPlugins.get(plugin.pluginId)
+      return previous !== undefined && digest(previous) !== digest(plugin)
+    })
+    .map((plugin) => plugin.pluginId)
+  return {
+    schemaVersion: 1,
+    changedSources: changedSources.toSorted(),
+    addedPlugins: addedPlugins.toSorted(),
+    removedPlugins: removedPlugins.toSorted(),
+    changedPlugins: changedPlugins.toSorted(),
+    skippedPlugins,
+    permissionSensitiveChanges: catalog.plugins
+      .flatMap((plugin) =>
+        plugin.securityClassification.permissionSensitiveChanges.map(
+          (type) => `${plugin.pluginId}:${type}`
+        )
+      )
+      .toSorted(),
+    contentResolution:
+      skippedPlugins.length > 0
+        ? 'complete-with-skips'
+        : catalog.plugins.some(
+              (plugin) => plugin.securityClassification.contentResolution === 'metadata-only'
+            )
+          ? 'metadata-only'
+          : 'complete',
+  }
+}

package/src/taxonomy.ts

@@ -0,0 +1,87 @@
+import { contentId } from './digest.js'
+
+export interface CategoryMap {
+  readonly aliases: Readonly<Record<string, string>>
+  readonly fallback: string
+}
+
+export interface ProductAliases {
+  readonly aliases: Readonly<Record<string, string>>
+}
+
+export function stablePluginId(sourceId: string, upstreamName: string): string {
+  return `plugin:${slug(sourceId)}:${slug(upstreamName)}`
+}
+
+export function stableReleaseId(
+  repositoryUrl: string,
+  subdirectory: string,
+  commitSha: string,
+  contentDigest: string
+): string {
+  return contentId('release', { repositoryUrl, subdirectory, commitSha, contentDigest })
+}
+
+export function normalizeCategory(value: string, map: CategoryMap): string {
+  const key = value.trim().toLocaleLowerCase()
+  return map.aliases[key] ?? (slug(key) || map.fallback)
+}
+
+export function productGroupingKey(name: string, aliases: ProductAliases): string {
+  const key = name.trim().toLocaleLowerCase()
+  return aliases.aliases[key] ?? slug(key)
+}
+
+/**
+ * Orders plugins so each category's curated leading products come first, in
+ * the configured order. Consumers preview the head of each category, so this
+ * ordering decides what users see before expanding.
+ */
+export function orderLeadingPlugins<
+  T extends {
+    readonly plugins: readonly {
+      categories: readonly string[]
+      upstreamPluginName: string
+    }[]
+  },
+>(catalog: T, leading?: Record<string, readonly string[]>): T {
+  if (!leading) return catalog
+  const leadRank = new Map<string, number>()
+  for (const [category, names] of Object.entries(leading)) {
+    names.forEach((name, index) => {
+      const key = `${category}::${name}`
+      if (!leadRank.has(key)) leadRank.set(key, index)
+    })
+  }
+  const rank = (plugin: T['plugins'][number]): number => {
+    let best = Number.POSITIVE_INFINITY
+    for (const category of plugin.categories) {
+      const value = leadRank.get(`${category}::${plugin.upstreamPluginName}`)
+      if (value !== undefined && value < best) best = value
+    }
+    return best
+  }
+  return {
+    ...catalog,
+    plugins: catalog.plugins.toSorted((left, right) => rank(left) - rank(right)),
+  }
+}
+
+function trimSlugEdges(value: string): string {
+  let start = 0
+  let end = value.length
+  while (start < end && value[start] === '-') start += 1
+  while (end > start && value[end - 1] === '-') end -= 1
+  return value.slice(start, end)
+}
+
+export function slug(value: string): string {
+  const result =
+    trimSlugEdges(
+      value
+        .trim()
+        .toLocaleLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+    ).slice(0, 128) || 'unknown'
+  return result.length < 2 ? `${result}-plugin` : result
+}