@adea-ai/plugins 3.0.9 → 4.0.0

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/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(

package/src/icons.ts

@@ -73,42 +73,20 @@ const MARK_WORDS = new Set([
   'logomark',
   'wordmark',
 ])
-const VARIANT_WORDS = new Set([
-  'large',
-  'small',
-  'light',
-  'dark',
-  'mono',
-  'white',
-  'black',
-  'positive',
-  'negative',
-  'color',
-  'colour',
-  'primary',
-  'secondary',
-  'horizontal',
-  'vertical',
-  'square',
-  'flat',
-  'glyph',
-])
-
 /**
  * Splits a file name into mark tokens. Separators are normalised because
  * vendors write marks as `logo.svg`, `atlan-logo.png`, `Dynatrace_Logo_color_positive.png`
  * or `cs logo big.png` alike.
  */
-function splitName(basename: string): { stems: string[]; marks: boolean; size: number } {
+function splitName(basename: string): { stemRank: number | undefined; size: number } {
   const withoutExtension = basename.slice(0, basename.lastIndexOf('.'))
   const words = withoutExtension
     .split(/[\s._-]+/)
     .filter(Boolean)
     .map((word) => word.toLowerCase())
   const size = words.some((word) => word === 'small') ? 1 : 0
-  const marks = words.some((word) => MARK_WORDS.has(word))
-  const stems = words.filter((word) => !MARK_WORDS.has(word) && !VARIANT_WORDS.has(word))
-  return { stems, marks, size }
+  const ranks = words.filter((word) => MARK_WORDS.has(word)).map((word) => STEM_RANK[word] ?? 0)
+  return { stemRank: ranks.length > 0 ? Math.min(...ranks) : undefined, size }
 }
 
 /**
@@ -133,9 +111,7 @@ export function selectIconPath(fileIndex: readonly string[]): string | null {
     const directories = segments.map((segment) => segment.toLowerCase())
     if (directories.some((segment) => EXCLUDED.test(segment))) continue
     if (directories.some((segment) => EXCLUDED_DIRECTORIES.includes(segment))) continue
-    const { stems, marks, size } = splitName(basename)
-    const single = stems.length === 1 ? stems[0]! : undefined
-    const stemRank = marks ? (single ? (STEM_RANK[single] ?? 0) : 0) : undefined
+    const { stemRank, size } = splitName(basename)
     const nested = directories.filter((segment) => DIRECTORY_RANK[segment] !== undefined)
     // A mark named as one — `logo.svg`, `atlan-logo.png`, `cs_logo_large.png` —
     // is accepted anywhere, including the plugin root. An unnamed image must sit
@@ -149,7 +125,8 @@ export function selectIconPath(fileIndex: readonly string[]): string | null {
           : 0
     if (!Number.isFinite(directoryRank)) continue
     const score = [stemRank ?? 5, directoryRank, size, EXTENSION_RANK[extension] ?? 9, path.length]
-    if (!best || compareScore(score, best.score) < 0) best = { path, score }
+    const comparison = best ? compareScore(score, best.score) : -1
+    if (!best || comparison < 0 || (comparison === 0 && path < best.path)) best = { path, score }
   }
   return best ? best.path : null
 }