@adea-ai/plugins 1.0.0

package/src/display-name.ts

@@ -0,0 +1,157 @@
+/**
+ * Display-name normalization for catalog plugins.
+ *
+ * Marketplace manifests are inconsistent: a vendor names a plugin `Gmail`, the
+ * next one names it `zapier`, and a curated source names it
+ * `aws-agents-for-devsecops`. The UI renders those strings verbatim, so one
+ * list reads `Zapier` and the next reads `zapier` beside it. This turns a
+ * slug-shaped name into the title-cased form a person would write, in the
+ * catalog, so every consumer shows the same thing without its own guesswork.
+ *
+ * Two rules keep it from "correcting" names that are already right:
+ *
+ * - a token that carries any uppercase is left exactly as it is, which
+ *   preserves vendor casing (`Gmail`, `iMessage`, `eToro`, `PDF Viewer`) and
+ *   makes the function idempotent;
+ * - a token with a published non-title-case form comes from `BRAND_TOKENS`
+ *   instead of the general rule, because title-casing `npm` → `Npm` or
+ *   `github` → `Github` is exactly the inconsistency this exists to remove.
+ */
+const BRAND_TOKENS: Readonly<Record<string, string>> = {
+  '42crunch': '42Crunch',
+  adlc: 'ADLC',
+  ai: 'AI',
+  bigquery: 'BigQuery',
+  brightdata: 'Bright Data',
+  amd: 'AMD',
+  alloydb: 'AlloyDB',
+  api: 'API',
+  apis: 'APIs',
+  aws: 'AWS',
+  cds: 'CDS',
+  ckeditor: 'CKEditor',
+  clickhouse: 'ClickHouse',
+  cli: 'CLI',
+  coderabbit: 'CodeRabbit',
+  crowdsec: 'CrowdSec',
+  crm: 'CRM',
+  crowdstrike: 'CrowdStrike',
+  css: 'CSS',
+  dak: 'DAK',
+  dominodatalab: 'Domino Data Lab',
+  datadog: 'Datadog',
+  fullstory: 'FullStory',
+  gitkraken: 'GitKraken',
+  devops: 'DevOps',
+  devsecops: 'DevSecOps',
+  gcp: 'GCP',
+  github: 'GitHub',
+  gitlab: 'GitLab',
+  graphql: 'GraphQL',
+  html: 'HTML',
+  huggingface: 'Hugging Face',
+  ibm: 'IBM',
+  idmp: 'IDMP',
+  imessage: 'iMessage',
+  ios: 'iOS',
+  javascript: 'JavaScript',
+  json: 'JSON',
+  k8s: 'Kubernetes',
+  langchain: 'LangChain',
+  llm: 'LLM',
+  llms: 'LLMs',
+  logrocket: 'LogRocket',
+  lsp: 'LSP',
+  lseg: 'LSEG',
+  macos: 'macOS',
+  md: 'MD',
+  mcp: 'MCP',
+  mongodb: 'MongoDB',
+  oracledb: 'Oracle Database',
+  pagerduty: 'PagerDuty',
+  planetscale: 'PlanetScale',
+  posthog: 'PostHog',
+  mysql: 'MySQL',
+  ngs: 'NGS',
+  nosql: 'NoSQL',
+  nvidia: 'NVIDIA',
+  ocr: 'OCR',
+  openai: 'OpenAI',
+  paypal: 'PayPal',
+  pdf: 'PDF',
+  postgres: 'Postgres',
+  postgresql: 'PostgreSQL',
+  pytorch: 'PyTorch',
+  sap: 'SAP',
+  sdk: 'SDK',
+  seo: 'SEO',
+  servicenow: 'ServiceNow',
+  sql: 'SQL',
+  sre: 'SRE',
+  tensorflow: 'TensorFlow',
+  terraform: 'Terraform',
+  twg: 'TWG',
+  typescript: 'TypeScript',
+  ui: 'UI',
+  ui5: 'UI5',
+  ux: 'UX',
+  whatsapp: 'WhatsApp',
+  wordpress: 'WordPress',
+  youtube: 'YouTube',
+}
+
+/** Articles, conjunctions and prepositions stay lowercase inside a name. */
+const SMALL_WORDS = new Set([
+  'a',
+  'an',
+  'and',
+  'as',
+  'at',
+  'by',
+  'for',
+  'from',
+  'in',
+  'of',
+  'on',
+  'or',
+  'the',
+  'to',
+  'with',
+])
+
+/**
+ * Names whose slug form hides a domain or an initialism, which the token rules
+ * below cannot recover: `monday-com` is `monday.com`, not `Monday Com`.
+ */
+const FULL_NAMES: Readonly<Record<string, string>> = {
+  'bigdata-com': 'BigData.com',
+  'incident-io': 'Incident.io',
+  'monday-com': 'Monday.com',
+  vpai: 'VPAI',
+}
+
+/**
+ * Title-cases a slug-shaped name and leaves a properly cased one alone.
+ *
+ * Separators become spaces (`adobe-for-creativity` → `Adobe for Creativity`),
+ * but a dot does not, so domain-style names keep their shape
+ * (`monday.com` → `Monday.com`).
+ */
+export function normalizeDisplayName(value: string): string {
+  const trimmed = value.trim()
+  const known = FULL_NAMES[trimmed.toLowerCase()]
+  if (known !== undefined) return known
+  const tokens = trimmed.split(/[-_\s]+/u).filter(Boolean)
+  if (tokens.length === 0) return value
+  return tokens
+    .map((token, index) => {
+      const key = token.toLowerCase()
+      const brand = BRAND_TOKENS[key]
+      if (brand !== undefined) return brand
+      // Any uppercase means the vendor already chose a casing.
+      if (/\p{Lu}/u.test(token)) return token
+      if (index > 0 && SMALL_WORDS.has(key)) return key
+      return `${token.slice(0, 1).toUpperCase()}${token.slice(1)}`
+    })
+    .join(' ')
+}

package/src/harness.ts

@@ -0,0 +1,202 @@
+import {
+  HarnessSchema,
+  MaterializationPlanSchema,
+  type Catalog,
+  type Harness,
+  type MaterializationPlan,
+  type Plugin,
+  type PluginRelease,
+} from './schema.js'
+
+export class MaterializationError extends Error {
+  constructor(
+    readonly code: string,
+    readonly details: readonly string[] = []
+  ) {
+    super(`${code}${details.length ? `: ${details.join(', ')}` : ''}`)
+    this.name = 'MaterializationError'
+  }
+}
+
+export function createMaterializationPlan(input: {
+  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])
+  const release = plugin.availableReleases.find(
+    (candidate) => candidate.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,
+    pluginId: plugin.pluginId,
+    releaseId: release.releaseId,
+    harness: input.harness,
+    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.`
+      ),
+    ],
+  })
+}
+
+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 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 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.`,
+  }
+}
+
+function capabilityTypeForPath(release: PluginRelease, path: string): string {
+  const match = release.capabilities.find((capability) => capability.paths.includes(path))
+  return match?.type ?? 'unknown'
+}
+
+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}`
+}
+
+function basenameWithoutExtension(path: string): string {
+  const basename = path.split('/').at(-1) ?? path
+  return basename.replace(/\.[^.]+$/, '')
+}
+
+export function supportedHarnesses(): readonly Harness[] {
+  return HarnessSchema.options
+}

package/src/icon-mirror.ts

@@ -0,0 +1,196 @@
+import { promises as fs } from 'node:fs'
+import { dirname, join } from 'node:path'
+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'
+
+/**
+ * Where an icon's bytes come from, so a mirror needs no tree walk and no
+ * rediscovery: `content` refetches a file at the pinned commit, `favicon`
+ * refetches the site icon the catalog recorded.
+ */
+export type IconSource =
+  | {
+      readonly kind: 'content'
+      readonly asset: string
+      readonly digest: string
+      readonly bytes: number
+      readonly contentType: IconContentType
+      readonly repositoryUrl: string
+      readonly commitSha: string
+      readonly pluginSubdirectory: string
+      /** Path relative to `pluginSubdirectory`, as recorded in the catalog. */
+      readonly path: string
+      /** Path including the plugin subdirectory, for a raw content fetch. */
+      readonly sourcePath: string
+    }
+  | {
+      readonly kind: 'favicon'
+      readonly asset: string
+      readonly digest: string
+      readonly bytes: number
+      readonly contentType: IconContentType
+      readonly url: string
+      readonly homepage: string
+    }
+
+export interface IconMirrorResult {
+  /** Icons whose verified bytes are present in the assets directory. */
+  readonly staged: readonly PublishedAsset[]
+  /** Icons that could not be staged, with the reason, never silently dropped. */
+  readonly skipped: readonly { readonly asset: string; readonly reason: string }[]
+}
+
+/**
+ * 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.
+ */
+export function resolveIconSources(
+  catalog: Pick<Catalog, 'plugins'>,
+  index: ConsumerIndex
+): readonly IconSource[] {
+  const byAsset = new Map<string, IconSource>()
+  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, {
+          kind: 'favicon',
+          asset,
+          digest: icon.digest,
+          bytes: icon.bytes,
+          contentType: icon.contentType,
+          url: icon.url,
+          homepage: icon.homepage,
+        })
+        continue
+      }
+      const subdirectory =
+        release.pluginSubdirectory && release.pluginSubdirectory !== '.'
+          ? release.pluginSubdirectory
+          : ''
+      byAsset.set(asset, {
+        kind: 'content',
+        asset,
+        digest: icon.digest,
+        bytes: icon.bytes,
+        contentType: icon.contentType,
+        repositoryUrl: release.resolvedRepositoryUrl,
+        commitSha: release.resolvedCommitSha,
+        pluginSubdirectory: subdirectory,
+        path: icon.path,
+        sourcePath: subdirectory ? `${subdirectory}/${icon.path}` : icon.path,
+      })
+    }
+  }
+  const sources: IconSource[] = []
+  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)
+  }
+  return sources.toSorted((left, right) => left.asset.localeCompare(right.asset))
+}
+
+/**
+ * Writes mirrored icon bytes beside the published artifacts.
+ *
+ * Bytes are verified against the digest the catalog advertises before they are
+ * staged, so a mirror can never publish content that differs from what the
+ * index promised. Staging never overwrites a differing file: content-addressed
+ * names make an existing file either identical or a build error.
+ */
+export async function stageIconAssets(input: {
+  readonly sources: readonly IconSource[]
+  readonly assetsDirectory: string
+  /** Reads the icon bytes for a source; live fetches raw content, offline reads fixtures. */
+  readonly readBytes: (source: IconSource) => Promise<Uint8Array>
+}): Promise<IconMirrorResult> {
+  const staged: PublishedAsset[] = []
+  const skipped: { asset: string; reason: string }[] = []
+  await fs.mkdir(input.assetsDirectory, { recursive: true })
+  for (const source of input.sources) {
+    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))
+      continue
+    }
+    if (existing) {
+      skipped.push({ asset: source.asset, reason: '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)}`,
+      })
+      continue
+    }
+    const inspected = inspectIconBytes(bytes)
+    if (!('contentType' in inspected)) {
+      skipped.push({ asset: source.asset, reason: inspected.rejected })
+      continue
+    }
+    if (inspected.contentType !== source.contentType) {
+      skipped.push({ asset: source.asset, reason: 'CONTENT_TYPE_CHANGED' })
+      continue
+    }
+    if (byteDigest(bytes) !== source.digest || bytes.byteLength !== source.bytes) {
+      skipped.push({ asset: source.asset, reason: 'DIGEST_MISMATCH' })
+      continue
+    }
+    await fs.mkdir(dirname(destination), { recursive: true })
+    await fs.writeFile(destination, bytes)
+    staged.push(publishedAssetOf(source))
+  }
+  // Distinct assets: two products can share one mark, and the catalog declares
+  // each asset once.
+  return { staged: dedupeAssets(staged), skipped }
+}
+
+function dedupeAssets(assets: readonly PublishedAsset[]): readonly PublishedAsset[] {
+  const unique = new Map<string, PublishedAsset>()
+  for (const asset of assets) unique.set(asset.name, asset)
+  return [...unique.values()]
+}
+
+function publishedAssetOf(source: IconSource): PublishedAsset {
+  return {
+    name: source.asset,
+    digest: source.digest,
+    bytes: source.bytes,
+    contentType: source.contentType,
+    kind: source.kind,
+    origin: source.kind === 'content' ? source.sourcePath : source.url,
+  }
+}
+
+/**
+ * Writes one verified icon into the assets directory.
+ *
+ * The build already holds the exact bytes it recorded a digest for, so staging
+ * them here removes the re-fetch a later mirror would need. That matters for
+ * site icons: their URL is not content-addressed, so a vendor can change the
+ * file between resolution and publication.
+ */
+export async function stageIconBytes(
+  assetsDirectory: string,
+  asset: string,
+  bytes: Uint8Array
+): Promise<void> {
+  const destination = join(assetsDirectory, asset)
+  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)
+}