@adea-ai/plugins 3.0.10 → 4.0.1

package/src/harness.ts

@@ -1,202 +1,281 @@
+import { isAbsolute, resolve, relative, sep } from 'node:path'
+import { realpath } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 import {
-  HarnessSchema,
-  MaterializationPlanSchema,
-  type Catalog,
-  type Harness,
-  type MaterializationPlan,
-  type Plugin,
-  type PluginRelease,
-} from './schema.js'
+  HarnessProfileSchema,
+  InstallationPlanSchema,
+  type HarnessProfile,
+  type McpServer,
+  type InstallationPlan,
+} from './agent-plugins-schema.js'
+import type { Catalog } from './schema.js'
+import { verifyPortableCatalog, PACKAGE_METADATA_KEY } from './portable-catalog.js'
+import { verifyAgentPackage, validateServer } from './agent-plugins-catalog.js'
 
-export class MaterializationError extends Error {
-  constructor(
-    readonly code: string,
-    readonly details: readonly string[] = []
-  ) {
-    super(`${code}${details.length ? `: ${details.join(', ')}` : ''}`)
-    this.name = 'MaterializationError'
-  }
+export interface InstallationInput {
+  readonly pluginId: string
+  readonly releaseId: string
+  readonly instanceId: string
+  readonly source: InstallationPlan['source']
+  readonly package: unknown
+  readonly profile: HarnessProfile
+  readonly requiredCredentials?: readonly string[]
+  readonly requiredConnectors?: readonly string[]
+  readonly allowPartial?: boolean
 }
-
-export function createMaterializationPlan(input: {
+export interface CatalogInstallationInput {
   readonly catalog: Catalog
   readonly pluginId: string
-  readonly harness: Harness
   readonly releaseId?: string
-}): MaterializationPlan {
-  const plugin = input.catalog.plugins.find((candidate) => candidate.pluginId === input.pluginId)
-  if (!plugin) throw new MaterializationError('PLUGIN_NOT_FOUND', [input.pluginId])
+  readonly instanceId: string
+  readonly profile: HarnessProfile
+  readonly allowPartial?: boolean
+}
+
+/** Resolve the exact catalog release before planning. The caller must also authenticate
+ * the catalog publisher and verify its artifact integrity before invoking this API.
+ */
+export function createCatalogInstallationPlan(input: CatalogInstallationInput): InstallationPlan {
+  verifyPortableCatalog(input.catalog)
+  const plugin = input.catalog.plugins.find((entry) => entry.pluginId === input.pluginId)
+  if (!plugin) throw new Error(`PLUGIN_NOT_FOUND: ${input.pluginId}`)
   const release = plugin.availableReleases.find(
-    (candidate) => candidate.releaseId === (input.releaseId ?? plugin.currentReleaseId)
+    (entry) => entry.releaseId === (input.releaseId ?? plugin.currentReleaseId)
   )
-  if (!release)
-    throw new MaterializationError('RELEASE_NOT_FOUND', [
-      input.releaseId ?? plugin.currentReleaseId,
-    ])
-  const compatibility = plugin.harnessCompatibility[input.harness]
-  if (!compatibility) throw new MaterializationError('HARNESS_UNSUPPORTED', [input.harness])
-  return MaterializationPlanSchema.parse({
-    planVersion: 1,
+  if (!release) throw new Error('RELEASE_NOT_FOUND')
+  if (release.contentResolution !== 'complete') throw new Error('COMPLETE_SOURCE_REQUIRED')
+  const pkg = release.releaseMetadata[PACKAGE_METADATA_KEY]
+  if (pkg === undefined)
+    throw new Error(
+      'PORTABLE_RESYNC_REQUIRED: run a full catalog sync before planning portable installation'
+    )
+  return createInstallationPlan({
     pluginId: plugin.pluginId,
     releaseId: release.releaseId,
-    harness: input.harness,
+    instanceId: input.instanceId,
+    profile: input.profile,
+    package: pkg,
+    allowPartial: input.allowPartial === true,
     source: {
       repositoryUrl: release.resolvedRepositoryUrl,
       commitSha: release.resolvedCommitSha,
       pluginSubdirectory: release.pluginSubdirectory,
       contentDigest: release.canonicalContentDigest,
     },
-    targetLayout: targetLayout(input.harness),
-    files: release.fileIndex
-      .map((sourcePath) => filePlan(release, sourcePath, input.harness, compatibility.status))
-      .toSorted(
-        (left, right) =>
-          left.targetPath.localeCompare(right.targetPath) ||
-          left.sourcePath.localeCompare(right.sourcePath)
-      ),
-    configuration: {
-      compatibilityStatus: compatibility.status,
-      sourceDialect: release.releaseMetadata.sourceDialect ?? 'unknown',
-      executeInstallation: false,
-    },
-    requiredConnectors: release.requiredConnectors,
     requiredCredentials: release.requiredCredentials,
-    policyConstraints: [
-      'This plan describes files and translation only; it does not install or execute upstream code.',
-      ...release.permissionSensitiveChanges.map(
-        (type) => `Control Plane must authorize ${type} capability explicitly.`
-      ),
-    ],
+    requiredConnectors: release.requiredConnectors,
   })
 }
 
-function targetLayout(harness: Harness): { root: string; notes: string[] } {
-  switch (harness) {
-    case 'codex':
-      return {
-        root: '.agents',
-        notes: [
-          'Skills and instructions map to the Codex .agents layout.',
-          'MCP and executable capabilities require Control Plane policy.',
-        ],
-      }
-    case 'claude-code':
-      return {
-        root: '.claude',
-        notes: [
-          'Claude Code-native files can be copied when the source dialect is Claude.',
-          'Hooks and MCP configuration still require explicit runtime authorization.',
-        ],
-      }
-    case 'cursor':
-      return {
-        root: '.cursor',
-        notes: [
-          'Cursor rules and skills map to the .cursor layout.',
-          'MCP configuration is declarative and is not executed by this plan.',
-        ],
-      }
-    case 'pi':
-      return {
-        root: '.pi',
-        notes: [
-          'Pi receives portable SKILL.md and MCP metadata only.',
-          'No Pi process or package lifecycle is invoked.',
-        ],
-      }
-    case 'hermes':
-      return {
-        root: '.hermes',
-        notes: [
-          'Hermes receives portable skill and MCP metadata only.',
-          'Harness-specific translation remains explicit in each file action.',
-        ],
-      }
-    case 'opencode':
-      return {
-        root: '.opencode',
-        notes: [
-          'OpenCode receives portable instruction and MCP metadata only.',
-          'Executable capabilities are excluded.',
-        ],
-      }
-    case 'generic-skill-mcp':
-      return {
-        root: '.agent',
-        notes: ['Generic SKILL.md and MCP-compatible files are copied when recognized.'],
-      }
-  }
+function identity(...parts: string[]): string {
+  return createHash('sha256').update(JSON.stringify(parts)).digest('hex')
 }
+/** A declarative proposal, never an execution grant. No brand-based support assumptions. */
+export function createInstallationPlan(input: InstallationInput): InstallationPlan {
+  const profile = HarnessProfileSchema.parse(input.profile)
+  const pkg = verifyAgentPackage(input.package)
+  if (pkg.sourceDigest !== input.source.contentDigest)
+    throw new Error('Package recipe does not match the selected immutable release.')
+  if (!input.instanceId || input.instanceId.length > 256)
+    throw new Error('A stable installation instanceId is required.')
+  const disabled: InstallationPlan['disabled'] = []
+  for (const item of pkg.nonPortable) disabled.push({ component: item.kind, reason: item.reason })
+  for (const item of pkg.diagnostics.filter((entry) => entry.severity === 'error'))
+    disabled.push({ component: item.path, reason: item.message })
 
-function filePlan(
-  release: PluginRelease,
-  sourcePath: string,
-  harness: Harness,
-  status: Plugin['harnessCompatibility'][Harness]['status']
-) {
-  const type = capabilityTypeForPath(release, sourcePath)
-  const directory = sourcePath.includes('/') ? sourcePath.slice(0, sourcePath.lastIndexOf('/')) : ''
-  if (status === 'unsupported' || type === 'executable' || type === 'unknown') {
-    return {
-      sourcePath,
-      targetPath: sourcePath,
-      action: 'unsupported' as const,
-      reason: `${type} capability is not executable through a materialization plan.`,
-    }
-  }
-  if (
-    type === 'hook' ||
-    type === 'browser' ||
-    type === 'scheduled-task' ||
-    type === 'ui-component'
-  ) {
-    return {
-      sourcePath,
-      targetPath: sourcePath,
-      action: 'ignore' as const,
-      reason: `${type} is cataloged but has no portable target layout for ${harness}.`,
+  const nativeEligible =
+    profile.agentPlugins.versions.includes(pkg.specVersion) &&
+    pkg.nonPortable.length === 0 &&
+    !Object.keys(pkg.manifest?.extensions ?? {}).length
+  const nativeCoverage =
+    (profile.agentPlugins.skills ? pkg.skills.length : 0) +
+    Object.values(pkg.mcpServers).filter((server) =>
+      profile.agentPlugins.mcpTransports.includes(server.type)
+    ).length
+  const adapterCoverage =
+    (profile.components.skillDirectories ? pkg.skills.length : 0) +
+    Object.values(pkg.mcpServers).filter((server) =>
+      profile.components.mcpTransports.includes(server.type)
+    ).length
+  const native = nativeEligible && nativeCoverage > 0 && nativeCoverage >= adapterCoverage
+  const strategy =
+    pkg.status === 'unavailable'
+      ? 'unavailable'
+      : native
+        ? 'native-agent-plugin'
+        : 'component-adapter'
+  let skillDirectories: string[] = []
+  const servers = new Map<string, McpServer>()
+  if (strategy !== 'unavailable') {
+    if (native ? profile.agentPlugins.skills : profile.components.skillDirectories)
+      skillDirectories = pkg.skills.map((skill) => skill.path)
+    else
+      for (const skill of pkg.skills)
+        disabled.push({
+          component: `skill:${skill.name}`,
+          reason: 'The selected adapter cannot expose skill directories.',
+        })
+    for (const [name, server] of Object.entries(pkg.mcpServers)) {
+      if (
+        (native ? profile.agentPlugins.mcpTransports : profile.components.mcpTransports).includes(
+          server.type
+        )
+      )
+        servers.set(name, server)
+      else
+        disabled.push({
+          component: `mcp:${name}`,
+          reason: `No ${server.type} MCP binding on this harness adapter.`,
+        })
     }
   }
-  const targetPath = targetForType(type, sourcePath, directory, harness)
-  const action =
-    type === 'skill' || type === 'rule' || (type === 'mcp-server' && status === 'native')
-      ? 'copy'
-      : 'translate'
-  return {
-    sourcePath,
-    targetPath,
-    action: action as 'copy' | 'translate',
-    reason:
-      action === 'copy'
-        ? `Copy recognized ${type} content.`
-        : `Translate ${type} metadata into the ${harness} layout.`,
-  }
+  const hasContent = skillDirectories.length > 0 || servers.size > 0
+  const compatibility = !hasContent ? 'unsupported' : disabled.length > 0 ? 'partial' : 'full'
+  const selectedStrategy =
+    !hasContent || (compatibility === 'partial' && !input.allowPartial) ? 'unavailable' : strategy
+  return InstallationPlanSchema.parse({
+    planVersion: 2,
+    pluginId: input.pluginId,
+    releaseId: input.releaseId,
+    instanceId: input.instanceId,
+    profile,
+    source: input.source,
+    package: pkg,
+    // Git source identity also pins executable modes, which the v1 byte snapshot omits.
+    packageKey: pkg.packageDigest
+      ? `packages/${identity(input.source.repositoryUrl, input.source.commitSha, input.source.pluginSubdirectory, pkg.packageDigest)}`
+      : '',
+    // Deliberately excludes release, package digest and harness. Switching harnesses or updating
+    // the same approved instance preserves data; distinct scopes use distinct instance IDs.
+    dataKey: `instances/${identity(input.pluginId, input.instanceId)}`,
+    preserveDataAcrossUpdates: true,
+    strategy: selectedStrategy,
+    compatibility,
+    allowedToActivate: false,
+    approvalRequired: true,
+    selection:
+      selectedStrategy === 'unavailable'
+        ? { skillDirectories: [], mcpServers: {} }
+        : { skillDirectories, mcpServers: Object.fromEntries(servers) },
+    disabled,
+    requiredCredentials: [...(input.requiredCredentials ?? [])],
+    requiredConnectors: [...(input.requiredConnectors ?? [])],
+    preconditions: [
+      'Verify catalog integrity/provenance and exact source digest before applying the package recipe.',
+      'Use an immutable package root; preserve source file modes and complete skill directories/resources.',
+      'Create a writable data directory for this instance; never key it by release or copy credentials between instances.',
+      'Control Plane must authorize activation, filesystem/network access, executables and credential bindings.',
+      'Recheck the actual harness/runtime/adapter profile and realpath containment immediately before activation.',
+      'Native mode registers exactly one package root. Component mode registers only the selected skill directories and MCP bindings, never legacy hooks/config files.',
+      'Do not install dependencies or run lifecycle scripts implicitly; review required executables and skill compatibility requirements.',
+      'Skill allowed-tools metadata is advisory and never grants permission.',
+      'Namespace registrations by installation identity; detect skill/server name collisions instead of overwriting existing harness configuration.',
+      'Remote authorization is client-managed. Do not expand remote URLs/headers or forward configured headers to another origin without authorization.',
+    ],
+  })
 }
 
-function capabilityTypeForPath(release: PluginRelease, path: string): string {
-  const match = release.capabilities.find((capability) => capability.paths.includes(path))
-  return match?.type ?? 'unknown'
+export interface RuntimeRoots {
+  readonly pluginRoot: string
+  readonly pluginData: string
 }
-
-function targetForType(type: string, path: string, directory: string, harness: Harness): string {
-  if (type === 'skill')
-    return `${targetLayout(harness).root}/skills/${directory || basenameWithoutExtension(path)}/${path.endsWith('SKILL.md') ? 'SKILL.md' : basenameWithoutExtension(path)}`
-  if (type === 'rule')
-    return `${targetLayout(harness).root}/rules/${basenameWithoutExtension(path)}.md`
-  if (type === 'command')
-    return `${targetLayout(harness).root}/commands/${basenameWithoutExtension(path)}.md`
-  if (type === 'agent')
-    return `${targetLayout(harness).root}/agents/${basenameWithoutExtension(path)}.md`
-  if (type === 'mcp-server')
-    return `${targetLayout(harness).root}/mcp/${basenameWithoutExtension(path)}.json`
-  return `${targetLayout(harness).root}/${path}`
+/** Exact, single-pass expansion. Replacement text is never scanned recursively. */
+export function expandPluginPaths(value: string, roots: RuntimeRoots): string {
+  return value.replace(/\$\{(PLUGIN_ROOT|PLUGIN_DATA)\}/g, (_match, name: string) =>
+    name === 'PLUGIN_ROOT' ? roots.pluginRoot : roots.pluginData
+  )
+}
+function within(path: string, root: string): boolean {
+  const suffix = relative(root, path)
+  return suffix === '' || (suffix !== '..' && !suffix.startsWith(`..${sep}`) && !isAbsolute(suffix))
 }
+export type McpBinding =
+  | {
+      type: 'stdio'
+      command: string
+      args: string[]
+      cwd: string
+      env: Record<string, string>
+      shell: false
+    }
+  | {
+      type: 'streamable-http' | 'sse'
+      url: string
+      headers: Record<string, string>
+      redirectPolicy: 'same-origin'
+      authorization: 'control-plane'
+    }
 
-function basenameWithoutExtension(path: string): string {
-  const basename = path.split('/').at(-1) ?? path
-  return basename.replace(/\.[^.]+$/, '')
+/** Produce concrete Control Plane launch/connect descriptors, without launching or connecting. */
+export function resolveMcpBinding(
+  input: McpServer,
+  roots: RuntimeRoots,
+  baseEnv: Readonly<Record<string, string>> = {},
+  platform: 'posix' | 'win32' = process.platform === 'win32' ? 'win32' : 'posix'
+): McpBinding {
+  const server = validateServer(input)
+  if (!isAbsolute(roots.pluginRoot) || !isAbsolute(roots.pluginData))
+    throw new Error('Runtime plugin roots must be absolute paths.')
+  if (server.type !== 'stdio')
+    return {
+      type: server.type,
+      url: server.url,
+      headers: { ...server.headers },
+      redirectPolicy: 'same-origin',
+      authorization: 'control-plane',
+    }
+  const command = server.command.startsWith('./')
+    ? resolve(roots.pluginRoot, server.command)
+    : server.command
+  if (server.command.startsWith('./') && !within(command, roots.pluginRoot))
+    throw new Error('Executable escapes the plugin root.')
+  const cwdInput = server.cwd ?? '${PLUGIN_ROOT}'
+  const cwdRoot = cwdInput.startsWith('${PLUGIN_DATA}') ? roots.pluginData : roots.pluginRoot
+  const expanded = expandPluginPaths(cwdInput, roots)
+  const cwd = resolve(roots.pluginRoot, expanded)
+  if (!within(cwd, cwdRoot)) throw new Error('Working directory escapes its declared root.')
+  const env: Record<string, string> = {}
+  const overlay = (name: string, value: string): void => {
+    if (platform === 'win32')
+      for (const existing of Object.keys(env))
+        if (existing.toUpperCase() === name.toUpperCase()) delete env[existing]
+    Object.defineProperty(env, name, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  }
+  for (const [key, value] of Object.entries(baseEnv)) overlay(key, value)
+  for (const [key, value] of Object.entries(server.env ?? {}))
+    overlay(key, expandPluginPaths(value, roots))
+  overlay('PLUGIN_ROOT', roots.pluginRoot)
+  overlay('PLUGIN_DATA', roots.pluginData)
+  return {
+    type: 'stdio',
+    command,
+    args: (server.args ?? []).map((arg) => expandPluginPaths(arg, roots)),
+    cwd,
+    env,
+    shell: false,
+  }
 }
 
-export function supportedHarnesses(): readonly Harness[] {
-  return HarnessSchema.options
+/** Mandatory filesystem preflight for Control Plane callers after safe materialization.
+ * Call immediately before activation inside the same protected installation boundary;
+ * a separate preflight is not a substitute for preventing concurrent filesystem mutation.
+ */
+export async function verifyBindingPaths(input: McpServer, roots: RuntimeRoots): Promise<void> {
+  const binding = resolveMcpBinding(input, roots)
+  if (binding.type !== 'stdio' || input.type !== 'stdio') return
+  const root = await realpath(roots.pluginRoot)
+  const data = await realpath(roots.pluginData)
+  if (root !== roots.pluginRoot || data !== roots.pluginData)
+    throw new Error('Supply canonical filesystem-resolved runtime roots.')
+  const cwd = await realpath(binding.cwd)
+  const expected = input.cwd?.startsWith('${PLUGIN_DATA}') ? data : root
+  if (!within(cwd, expected))
+    throw new Error('Working directory resolves outside its declared root.')
+  if (input.command.startsWith('./') && !within(await realpath(binding.command), root))
+    throw new Error('Executable resolves outside the package root.')
 }

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/icons.test.ts

@@ -29,6 +29,8 @@ const CLEAN_SVG =
 describe('icon file selection', () => {
   test('prefers the conventional mark in a conventional location', () => {
     expect(selectIconPath(['assets/logo.png', 'assets/icon.svg'])).toBe('assets/icon.svg')
+    expect(selectIconPath(['assets/brand.svg', 'assets/icon.png'])).toBe('assets/icon.png')
+    expect(selectIconPath(['assets/logo.svg', 'assets/avatar.svg'])).toBe('assets/avatar.svg')
     expect(selectIconPath(['assets/logo.png', 'docs/media/logo.png'])).toBe('assets/logo.png')
     expect(selectIconPath(['images/logo.png', 'assets/logo.png'])).toBe('assets/logo.png')
   })
@@ -58,6 +60,9 @@ describe('icon file selection', () => {
     expect(selectIconPath(['assets/logo.txt', 'assets/logo.svg'])).toBe('assets/logo.svg')
     expect(selectIconPath(['../assets/logo.svg'])).toBeNull()
     expect(selectIconPath([])).toBeNull()
+    const tied = ['assets/aaa-logo.svg', 'assets/zzz-logo.svg']
+    expect(selectIconPath(tied)).toBe('assets/aaa-logo.svg')
+    expect(selectIconPath(tied.toReversed())).toBe('assets/aaa-logo.svg')
     // An unnamed image at the plugin root is as likely a screenshot as a mark.
     expect(selectIconPath(['screenshot.png', 'readme.md'])).toBeNull()
     expect(selectIconPath(['assets/logo.png', 'assets/logo.svg'])).toBe(