@adea-ai/plugins 1.0.0

package/src/schema.ts

@@ -0,0 +1,309 @@
+import { z } from 'zod'
+
+export const DIGEST_RE = /^sha256:[a-f0-9]{64}$/
+export const SHA_RE = /^[a-f0-9]{40}$/
+
+export const DigestSchema = z.string().regex(DIGEST_RE)
+export const ShaSchema = z.string().regex(SHA_RE)
+export const TimestampSchema = z.string().datetime({ offset: true })
+
+export const MarketplaceDialectSchema = z.enum(['openai', 'cursor', 'claude'])
+export const TrustClassificationSchema = z.enum(['official'])
+export const SyncStatusSchema = z.enum(['synchronized', 'unchanged', 'failed'])
+
+export const CapabilityTypeSchema = z.enum([
+  'skill',
+  'mcp-server',
+  'connector',
+  'command',
+  'agent',
+  'hook',
+  'rule',
+  'browser',
+  'scheduled-task',
+  'ui-component',
+  'executable',
+  'unknown',
+])
+
+export const HarnessSchema = z.enum([
+  'codex',
+  'claude-code',
+  'cursor',
+  'pi',
+  'hermes',
+  'opencode',
+  'generic-skill-mcp',
+])
+export type Harness = z.output<typeof HarnessSchema>
+
+export const CompatibilityStatusSchema = z.enum([
+  'native',
+  'portable',
+  'requires-translation',
+  'partially-supported',
+  'unsupported',
+  'blocked-by-policy',
+  'unknown',
+])
+
+const JsonValueSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+  ])
+)
+
+export const JsonObjectSchema = z.record(z.string(), JsonValueSchema)
+
+export const CatalogSourceSchema = z
+  .object({
+    sourceId: z.string().regex(/^[a-z0-9][a-z0-9-]{1,63}$/),
+    displayName: z.string().min(1).max(160),
+    repositoryUrl: z.string().url(),
+    marketplaceDialect: MarketplaceDialectSchema,
+    manifestPath: z.string().min(1).max(512),
+    defaultBranch: z.string().regex(/^[A-Za-z0-9._/-]+$/),
+    resolvedCommitSha: ShaSchema,
+    retrievalTimestamp: TimestampSchema,
+    trustClassification: TrustClassificationSchema,
+    sourceManifestDigest: DigestSchema,
+    synchronizationStatus: SyncStatusSchema,
+  })
+  .strict()
+
+export const CapabilitySchema = z
+  .object({
+    type: CapabilityTypeSchema,
+    name: z.string().min(1).max(200),
+    paths: z.array(z.string().min(1).max(512)).max(512),
+    metadata: JsonObjectSchema,
+    securityImpact: z.enum(['none', 'review', 'sensitive']),
+  })
+  .strict()
+
+export const HarnessCompatibilitySchema = z
+  .object({
+    status: CompatibilityStatusSchema,
+    reasons: z.array(z.string().min(1).max(500)).max(64),
+    responsibleCapabilities: z.array(CapabilityTypeSchema).max(32),
+  })
+  .strict()
+
+export const LicenseMetadataSchema = z
+  .object({
+    name: z.string().min(1).max(200),
+    spdxId: z.string().min(1).max(100).optional(),
+    url: z.string().url().optional(),
+    source: z.enum(['plugin-manifest', 'package-manifest', 'marketplace-entry', 'unknown']),
+  })
+  .strict()
+
+export const SecurityClassificationSchema = z
+  .object({
+    level: z.enum(['low', 'review', 'sensitive']),
+    reasons: z.array(z.string().min(1).max(500)).max(64),
+    permissionSensitiveChanges: z.array(z.string().min(1).max(200)).max(64),
+    contentResolution: z.enum(['complete', 'metadata-only']),
+  })
+  .strict()
+
+export const PluginProvenanceSchema = z
+  .object({
+    sourceId: z.string().min(1),
+    repositoryUrl: z.string().url(),
+    manifestPath: z.string().min(1),
+    pluginSubdirectory: z.string().min(1),
+    resolvedCommitSha: ShaSchema,
+    sourceManifestDigest: DigestSchema,
+    upstreamEntryDigest: DigestSchema,
+  })
+  .strict()
+
+export const IconContentTypeSchema = z.enum([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+  'image/x-icon',
+])
+
+export const PluginReleaseSchema = z
+  .object({
+    releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
+    upstreamVersion: z.string().min(1).max(128).optional(),
+    resolvedRepositoryUrl: z.string().url(),
+    resolvedCommitSha: ShaSchema,
+    pluginSubdirectory: z.string().min(1).max(512),
+    canonicalContentDigest: DigestSchema,
+    manifestDigest: DigestSchema,
+    contentResolution: z.enum(['complete', 'metadata-only']),
+    releaseMetadata: JsonObjectSchema,
+    capabilities: z.array(CapabilitySchema).max(1024),
+    requiredConnectors: z.array(z.string().min(1).max(200)).max(128),
+    requiredCredentials: z.array(z.string().min(1).max(200)).max(128),
+    permissionSensitiveChanges: z.array(z.string().min(1).max(200)).max(128),
+    fileIndex: z.array(z.string().min(1).max(512)).max(4096),
+    publicationTimestamp: TimestampSchema,
+    /**
+     * Brand mark resolved at compile time. `content` comes from the release's
+     * own files; `favicon` comes from the product's declared homepage, for
+     * products that ship no mark of their own.
+     */
+    icon: z
+      .discriminatedUnion('kind', [
+        z
+          .object({
+            kind: z.literal('content'),
+            path: z.string().min(1).max(512),
+            contentType: IconContentTypeSchema,
+            digest: DigestSchema,
+            bytes: z.number().int().positive().max(1048576),
+          })
+          .strict(),
+        z
+          .object({
+            kind: z.literal('favicon'),
+            url: z.string().url().max(1024),
+            homepage: z.string().url().max(1024),
+            contentType: IconContentTypeSchema,
+            digest: DigestSchema,
+            bytes: z.number().int().positive().max(1048576),
+          })
+          .strict(),
+      ])
+      .optional(),
+  })
+  .strict()
+
+export const PluginSchema = z
+  .object({
+    pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
+    displayName: z.string().min(1).max(200),
+    description: z.string().max(4096),
+    productGroupingKey: z.string().regex(/^[a-z0-9][a-z0-9-]{1,127}$/),
+    categories: z.array(z.string().regex(/^[a-z0-9][a-z0-9-]{1,63}$/)).max(32),
+    keywords: z.array(z.string().min(1).max(100)).max(128),
+    authors: z.array(z.string().min(1).max(200)).max(32),
+    homepage: z.string().url().optional(),
+    icons: z.array(z.string().min(1).max(1024)).max(16),
+    sourceId: z.string().min(1),
+    upstreamPluginName: z.string().min(1).max(200),
+    currentReleaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
+    availableReleases: z.array(PluginReleaseSchema).min(1).max(128),
+    capabilitySummary: z.partialRecord(CapabilityTypeSchema, z.number().int().nonnegative()),
+    harnessCompatibility: z.record(HarnessSchema, HarnessCompatibilitySchema),
+    license: LicenseMetadataSchema,
+    provenance: PluginProvenanceSchema,
+    securityClassification: SecurityClassificationSchema,
+  })
+  .strict()
+
+export const CatalogSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
+    generatedAt: TimestampSchema,
+    sources: z.array(CatalogSourceSchema).min(1).max(64),
+    plugins: z.array(PluginSchema).max(4096),
+  })
+  .strict()
+
+export const SourceLockEntrySchema = z
+  .object({
+    sourceId: z.string().min(1),
+    repositoryUrl: z.string().url(),
+    defaultBranch: z.string().min(1),
+    resolvedCommitSha: ShaSchema,
+    manifestPath: z.string().min(1),
+    marketplaceDialect: MarketplaceDialectSchema,
+    sourceManifestDigest: DigestSchema,
+    retrievedAt: TimestampSchema,
+    synchronizationStatus: SyncStatusSchema,
+    pluginPins: z
+      .array(
+        z
+          .object({
+            pluginName: z.string().min(1).max(200),
+            repositoryUrl: z.string().url(),
+            pluginSubdirectory: z.string().max(512),
+            resolvedCommitSha: ShaSchema,
+          })
+          .strict()
+      )
+      .max(4096),
+  })
+  .strict()
+
+export const SourcesLockSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    lockId: z.string().regex(/^lock:[a-f0-9]{64}$/),
+    sources: z.array(SourceLockEntrySchema).min(1).max(64),
+  })
+  .strict()
+
+export const MaterializationPlanSchema = z
+  .object({
+    planVersion: z.literal(1),
+    pluginId: PluginSchema.shape.pluginId,
+    releaseId: PluginReleaseSchema.shape.releaseId,
+    harness: HarnessSchema,
+    source: z
+      .object({
+        repositoryUrl: z.string().url(),
+        commitSha: ShaSchema,
+        pluginSubdirectory: z.string().min(1),
+        contentDigest: DigestSchema,
+      })
+      .strict(),
+    targetLayout: z
+      .object({
+        root: z.string().min(1),
+        notes: z.array(z.string().min(1)).max(32),
+      })
+      .strict(),
+    files: z
+      .array(
+        z
+          .object({
+            sourcePath: z.string().min(1),
+            targetPath: z.string().min(1),
+            action: z.enum(['copy', 'translate', 'ignore', 'unsupported']),
+            reason: z.string().min(1).max(500),
+          })
+          .strict()
+      )
+      .max(4096),
+    configuration: JsonObjectSchema,
+    requiredConnectors: z.array(z.string().min(1)).max(128),
+    requiredCredentials: z.array(z.string().min(1)).max(128),
+    policyConstraints: z.array(z.string().min(1)).max(128),
+  })
+  .strict()
+
+export type CatalogSource = z.output<typeof CatalogSourceSchema>
+export type Capability = z.output<typeof CapabilitySchema>
+export type HarnessCompatibility = z.output<typeof HarnessCompatibilitySchema>
+export type LicenseMetadata = z.output<typeof LicenseMetadataSchema>
+export type SecurityClassification = z.output<typeof SecurityClassificationSchema>
+export type PluginProvenance = z.output<typeof PluginProvenanceSchema>
+export type PluginRelease = z.output<typeof PluginReleaseSchema>
+export type Plugin = z.output<typeof PluginSchema>
+export type Catalog = z.output<typeof CatalogSchema>
+export type SourceLockEntry = z.output<typeof SourceLockEntrySchema>
+export type SourcesLock = z.output<typeof SourcesLockSchema>
+export type MaterializationPlan = z.output<typeof MaterializationPlanSchema>
+
+export function parseCatalog(input: unknown): Catalog {
+  return CatalogSchema.parse(input)
+}
+
+export function parseSourcesLock(input: unknown): SourcesLock {
+  return SourcesLockSchema.parse(input)
+}

package/src/site-icon-fallback.test.ts

@@ -0,0 +1,267 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  buildCatalog,
+  byteDigest,
+  digest,
+  type CatalogPolicy,
+  type CategoryMap,
+  type ProductAliases,
+  type ResolvedSource,
+  type Snapshot,
+  type SnapshotLoader,
+} from './index.js'
+import { buildConsumerIndex } from './consumer-index.js'
+import { resolveIconSources, stageIconAssets } from './icon-mirror.js'
+import { selectIconPath } from './icons.js'
+
+/**
+ * End-to-end cover for the brand-mark fallback: a plugin that ships no mark of
+ * its own gets the product site's icon, resolved during the build, recorded in
+ * the catalog and carried into the consumer index and its asset manifest.
+ */
+
+const PNG = new Uint8Array([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+])
+const HOME = 'https://vendor.example/'
+const APPLE_ICON = 'https://vendor.example/apple-icon.png'
+
+const policy: CatalogPolicy = {
+  allowedRepositoryHosts: ['github.com'],
+  allowedRepositoryProtocols: ['https:'],
+  maxFilesPerPlugin: 4096,
+  maxBytesPerPlugin: 50 * 1024 * 1024,
+  maxFileBytes: 5 * 1024 * 1024,
+  maxMarketplacePlugins: 4096,
+  denyExecutableLifecycleScripts: true,
+  publishRequiresCompleteContent: false,
+  sensitiveCapabilityTypes: ['mcp-server', 'hook', 'executable'],
+}
+const categoryMap: CategoryMap = { aliases: {}, fallback: 'other' }
+const productAliases: ProductAliases = { aliases: {} }
+
+/** Serves plugin content from memory, so no filesystem or tree fetch is needed. */
+function loader(files: Record<string, Uint8Array>): SnapshotLoader {
+  return {
+    load: async (): Promise<Snapshot> => ({ files: new Map(Object.entries(files)), symlinks: [] }),
+  }
+}
+
+function source(entryName: string, homepage?: string): ResolvedSource {
+  return {
+    config: {
+      sourceId: 'test-source',
+      displayName: 'Test Source',
+      repositoryUrl: 'https://github.com/acme/marketplace',
+      marketplaceDialect: 'claude',
+      manifestPath: 'marketplace.json',
+      defaultBranch: 'main',
+      trustClassification: 'official',
+    },
+    commitSha: 'a'.repeat(40),
+    manifestText: '{}',
+    parsed: {
+      marketplaceName: 'Acme',
+      marketplaceDescription: 'Acme',
+      owner: ['Acme'],
+      entries: [
+        {
+          name: entryName,
+          description: `${entryName} plugin`,
+          categories: ['productivity'],
+          keywords: [],
+          authors: ['Acme'],
+          icons: [],
+          ...(homepage ? { homepage } : {}),
+          source: { kind: 'local', path: '.' },
+          policy: {},
+          raw: {},
+          entryDigest: `sha256:${'e'.repeat(64)}`,
+        },
+      ],
+      raw: {},
+    },
+    pluginPins: [],
+    retrievedAt: '2026-01-01T00:00:00.000Z',
+    manifestDigest: digest('{}'),
+  }
+}
+
+function stubFetch(handler: (url: string) => Response) {
+  const original = globalThis.fetch
+  const calls: string[] = []
+  globalThis.fetch = (async (input: unknown) => {
+    const url = String(input)
+    calls.push(url)
+    return handler(url)
+  }) as typeof fetch
+  return { calls, restore: () => void (globalThis.fetch = original) }
+}
+
+async function build(entryName: string, homepage?: string, options: { live?: boolean } = {}) {
+  const stub = stubFetch((url) => {
+    if (url === HOME)
+      return new Response(`<head><link rel="apple-touch-icon" href="/apple-icon.png"></head>`, {
+        status: 200,
+      })
+    if (url === APPLE_ICON) return new Response(PNG, { status: 200 })
+    return new Response('missing', { status: 404 })
+  })
+  try {
+    const catalog = await buildCatalog({
+      resolvedSources: [source(entryName, homepage)],
+      categoryMap,
+      productAliases,
+      policy,
+      metadataOnly: false,
+      snapshotLoader: loader({ 'README.md': new TextEncoder().encode('no mark here') }),
+      resolveExternalRefs: options.live ?? true,
+    })
+    return { catalog, calls: stub.calls }
+  } finally {
+    stub.restore()
+  }
+}
+
+describe('product site icon fallback', () => {
+  test('records the site icon for a plugin that ships no mark', async () => {
+    const { catalog, calls } = await build('connector', HOME)
+    const release = catalog.plugins[0]!.availableReleases[0]!
+    expect(release.icon).toEqual({
+      kind: 'favicon',
+      url: APPLE_ICON,
+      homepage: HOME,
+      contentType: 'image/png',
+      digest: byteDigest(PNG),
+      bytes: PNG.byteLength,
+    })
+    expect(calls).toEqual([HOME, APPLE_ICON])
+  })
+
+  test('prefers the plugin content and never contacts the site when a mark exists', async () => {
+    const stub = stubFetch(() => new Response('unexpected', { status: 500 }))
+    try {
+      const catalog = await buildCatalog({
+        resolvedSources: [source('connector', HOME)],
+        categoryMap,
+        productAliases,
+        policy,
+        metadataOnly: false,
+        snapshotLoader: loader({
+          'assets/logo.svg': new TextEncoder().encode(
+            '<svg xmlns="http://www.w3.org/2000/svg"><rect width="8" height="8"/></svg>'
+          ),
+        }),
+        resolveExternalRefs: true,
+      })
+      expect(catalog.plugins[0]!.availableReleases[0]!.icon).toMatchObject({
+        kind: 'content',
+        path: 'assets/logo.svg',
+      })
+      expect(stub.calls).toEqual([])
+    } finally {
+      stub.restore()
+    }
+  })
+
+  test('does not reach the network for a metadata-only build', async () => {
+    const { catalog, calls } = await build('connector', HOME, { live: false })
+    expect(calls).toEqual([])
+    expect(catalog.plugins[0]!.availableReleases[0]!.icon).toBeUndefined()
+  })
+
+  test('skips a repository homepage, which would only yield the forge logo', async () => {
+    const { catalog, calls } = await build('connector', 'https://github.com/acme/connector')
+    expect(calls).toEqual([])
+    expect(catalog.plugins[0]!.availableReleases[0]!.icon).toBeUndefined()
+  })
+
+  test('carries the site icon into the index, the manifest and the mirror', async () => {
+    const { catalog } = await build('connector', HOME)
+    const index = buildConsumerIndex({ catalog })
+    const product = index.products.connector!
+    expect(product.icon).toMatchObject({ kind: 'favicon', url: APPLE_ICON, homepage: HOME })
+    expect(product.monogram.text).toBe('CO')
+
+    const sources = resolveIconSources(catalog, index)
+    expect(sources).toEqual([
+      {
+        kind: 'favicon',
+        asset: product.icon!.asset,
+        digest: byteDigest(PNG),
+        bytes: PNG.byteLength,
+        contentType: 'image/png',
+        url: APPLE_ICON,
+        homepage: HOME,
+      },
+    ])
+
+    const staged = await stageIconAssets({
+      sources,
+      assetsDirectory: `${import.meta.dir}/.icon-mirror-test`,
+      readBytes: async () => PNG,
+    })
+    expect(staged.skipped).toEqual([])
+    expect(staged.staged.map((asset) => asset.origin)).toEqual([APPLE_ICON])
+    expect(staged.staged[0]!.kind).toBe('favicon')
+    await Bun.$`rm -rf ${`${import.meta.dir}/.icon-mirror-test`}`.quiet()
+  })
+
+  test('a curated site override supplies the mark for a repository-only plugin', async () => {
+    const stub = stubFetch((url) => {
+      if (url === 'https://curated.example/')
+        return new Response('<head><link rel="apple-touch-icon" href="/mark.png"></head>')
+      if (url === 'https://curated.example/mark.png') return new Response(PNG)
+      return new Response('missing', { status: 404 })
+    })
+    try {
+      const catalog = await buildCatalog({
+        resolvedSources: [source('connector', 'https://github.com/acme/connector')],
+        categoryMap,
+        productAliases,
+        productIconOverrides: {
+          schemaVersion: 1,
+          overrides: { connector: 'https://curated.example/' },
+        },
+        policy,
+        metadataOnly: false,
+        snapshotLoader: loader({ 'README.md': new TextEncoder().encode('x') }),
+        resolveExternalRefs: true,
+      })
+      expect(catalog.plugins[0]!.availableReleases[0]!.icon).toMatchObject({
+        kind: 'favicon',
+        url: 'https://curated.example/mark.png',
+        homepage: 'https://curated.example/',
+      })
+      expect(stub.calls).toEqual(['https://curated.example/', 'https://curated.example/mark.png'])
+    } finally {
+      stub.restore()
+    }
+  })
+
+  test('falls back to a monogram when the site yields no usable icon', async () => {
+    const stub = stubFetch((url) =>
+      url === HOME
+        ? new Response('<head><link rel="icon" href="/broken.png"></head>', { status: 200 })
+        : new Response('not an image', { status: 200 })
+    )
+    try {
+      const catalog = await buildCatalog({
+        resolvedSources: [source('connector', HOME)],
+        categoryMap,
+        productAliases,
+        policy,
+        metadataOnly: false,
+        snapshotLoader: loader({ 'README.md': new TextEncoder().encode('x') }),
+        resolveExternalRefs: true,
+      })
+      expect(catalog.plugins[0]!.availableReleases[0]!.icon).toBeUndefined()
+      const index = buildConsumerIndex({ catalog })
+      expect(index.products.connector!.icon).toBeNull()
+      expect(index.products.connector!.monogram).toEqual({ text: 'CO', hue: expect.any(Number) })
+      expect(selectIconPath(catalog.plugins[0]!.availableReleases[0]!.fileIndex!)).toBeNull()
+    } finally {
+      stub.restore()
+    }
+  })
+})