@adea-ai/plugins 4.0.1 → 4.0.7

package/src/artifacts.ts

@@ -0,0 +1,234 @@
+import { publishCatalog, type PublishOptions } from './catalog-store.js'
+import {
+  buildConsumerIndex,
+  CATALOG_INDEX_ARTIFACT,
+  iconCoverage,
+  type ConsumerIndex,
+  type ProductPreference,
+} from './consumer-index.js'
+import { digest } from './digest.js'
+import { publishedAssetOf, type PublishedAsset } from './integrity-manifest.js'
+import { catalogIdSuffix, immutableAssetUrl } from './publication.js'
+import type { Catalog, SourcesLock } from './schema.js'
+
+/**
+ * Published artifacts by file name. The core six are always present; the
+ * consumer shards (`catalog-index.v1.json`, `shelf-<category>.v1.json` and
+ * `category-<category>.v1.json`) follow the configured categories.
+ */
+export interface GeneratedArtifacts {
+  readonly [name: string]: string
+  readonly 'catalog.v1.json': string
+  readonly 'catalog-summary.v1.json': string
+  readonly 'sources.lock.json': string
+  readonly 'compatibility.v1.json': string
+  readonly 'categories.v1.json': string
+  readonly 'integrity.json': string
+}
+
+export interface ConsumerIndexOptions {
+  readonly leading?: Readonly<Record<string, readonly string[]>>
+  readonly topCount?: number
+  readonly productPreference?: ProductPreference
+  /**
+   * Where this catalog is published. When known, product records carry an
+   * absolute, immutable URL for their brand mark so no client composes one.
+   */
+  readonly publicationRepositoryUrl?: string
+  /**
+   * Base URL of the committed asset directory that browsers fetch directly.
+   *
+   * GitHub release assets answer a cross-origin `fetch` with no CORS header and
+   * redirect through a URL that cannot be cached, so a browser neither reads the
+   * index nor reuses an icon. The same files served from the repository are
+   * CORS-enabled, direct and cacheable.
+   */
+  readonly publicationAssetsBaseUrl?: string
+  /**
+   * Base URL of the content-addressed snapshot directory, one level below the
+   * asset branch. Catalog artifacts are addressed by catalog identity, so they
+   * live in `catalogs/<catalogId>/` while digest-addressed brand marks sit at
+   * the branch root.
+   */
+  readonly publicationCatalogsBaseUrl?: string
+  /**
+   * Whether curated-name drift is published in the consumer index. An offline
+   * build replays fixtures rather than the upstream catalogs, so its curation
+   * findings are noise and are omitted by default.
+   */
+  readonly curationDiagnostics?: boolean
+}
+
+export function createArtifacts(
+  catalog: Catalog,
+  lock: SourcesLock,
+  options: ConsumerIndexOptions = {}
+): GeneratedArtifacts {
+  const index = buildConsumerIndex({ ...options, catalog })
+  const summary = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    generatedAt: catalog.generatedAt,
+    sourceCount: catalog.sources.length,
+    pluginCount: catalog.plugins.length,
+    categories: [...new Set(catalog.plugins.flatMap((plugin) => plugin.categories))].toSorted(),
+    productGroups: [
+      ...new Set(catalog.plugins.map((plugin) => plugin.productGroupingKey)),
+    ].toSorted(),
+    search: catalog.plugins
+      .map((plugin) => ({
+        pluginId: plugin.pluginId,
+        text: `${plugin.displayName} ${plugin.description} ${plugin.keywords.join(' ')}`.trim(),
+      }))
+      .toSorted((left, right) => left.pluginId.localeCompare(right.pluginId)),
+  }
+  const compatibility = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    plugins: catalog.plugins.map((plugin) => ({
+      pluginId: plugin.pluginId,
+      harnessCompatibility: plugin.harnessCompatibility,
+    })),
+  }
+  // Navigation stays small and points at the shards a client then fetches:
+  // `shelf-*` for a default view, `category-*` for "view more", and
+  // `catalog-index.v1.json` for the complete product list.
+  const navigation = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    generatedAt: catalog.generatedAt,
+    topCount: index.topCount,
+    sourcePreference: index.sourcePreference,
+    counts: index.counts,
+    catalogIndexArtifact: CATALOG_INDEX_ARTIFACT,
+    iconCoverage: iconCoverage(index),
+    // The index URL rides in the navigation artifact so a client can fetch the
+    // browsing index from the publication it was told about, verify it against
+    // the digest in integrity.json, and never compose a URL or need this
+    // service to proxy it. Absent for an unpublished build.
+    ...(options.publicationCatalogsBaseUrl
+      ? {
+          catalogIndexUrl: `${options.publicationCatalogsBaseUrl}/${catalogIdSuffix(catalog.catalogId)}/${CATALOG_INDEX_ARTIFACT}`,
+        }
+      : options.publicationAssetsBaseUrl
+        ? { catalogIndexUrl: `${options.publicationAssetsBaseUrl}/${CATALOG_INDEX_ARTIFACT}` }
+        : options.publicationRepositoryUrl
+          ? {
+              catalogIndexUrl: immutableAssetUrl(
+                options.publicationRepositoryUrl,
+                catalog.catalogId,
+                CATALOG_INDEX_ARTIFACT
+              ),
+            }
+          : {}),
+    // Marks ride in the navigation artifact so a client that already receives it
+    // renders compiled brand marks without fetching the browsing index. Keys are
+    // sorted for a stable artifact.
+    brandMarks: Object.fromEntries(
+      Object.keys(index.products)
+        .toSorted()
+        .flatMap((productKey) => {
+          const assetUrl = index.products[productKey]?.icon?.assetUrl
+          return assetUrl ? [[productKey, assetUrl] as const] : []
+        })
+    ),
+    categories: index.categories,
+    diagnostics: options.curationDiagnostics === false ? [] : index.diagnostics,
+  }
+  const shards: Record<string, string> = {
+    [CATALOG_INDEX_ARTIFACT]: json({
+      schemaVersion: 1,
+      catalogId: catalog.catalogId,
+      generatedAt: catalog.generatedAt,
+      topCount: index.topCount,
+      sourcePreference: index.sourcePreference,
+      counts: index.counts,
+      products: index.products,
+      categories: index.categories.map((category) => ({
+        category: category.category,
+        productCount: category.productCount,
+        productKeys: category.productKeys,
+      })),
+    }),
+  }
+  for (const category of index.categories) {
+    shards[category.shelfArtifact] = json({
+      schemaVersion: 1,
+      catalogId: catalog.catalogId,
+      category: category.category,
+      topCount: index.topCount,
+      products: category.topProductKeys.map((productKey) => index.products[productKey]),
+    })
+    shards[category.listArtifact] = json({
+      schemaVersion: 1,
+      catalogId: catalog.catalogId,
+      category: category.category,
+      productCount: category.productCount,
+      pluginCount: category.pluginCount,
+      products: category.productKeys.map((productKey) => index.products[productKey]),
+    })
+  }
+  const files: Record<string, string> = {
+    'catalog.v1.json': json(catalog),
+    'catalog-summary.v1.json': json(summary),
+    'sources.lock.json': json(lock),
+    'compatibility.v1.json': json(compatibility),
+    'categories.v1.json': json(navigation),
+    ...shards,
+  }
+  const integrityBody = {
+    schemaVersion: 1,
+    catalogId: catalog.catalogId,
+    // An artifact's digest is the canonical digest of its text, not a hash of
+    // the file bytes: consumers read the artifact as a string and compare it
+    // with `canonicalDigest`, so a checker hashing the raw bytes will disagree
+    // with every published release. Mirrored marks below are the byte case,
+    // because a client stores those bytes.
+    files: Object.fromEntries(
+      Object.entries(files)
+        .toSorted()
+        .map(([name, content]) => [name, digest(content)])
+    ),
+    // Mirrored brand marks are published next to the artifacts, never inside
+    // them: the digest and size let a consumer or the release check verify the
+    // bytes it fetched without trusting the release listing.
+    assets: iconAssets(index),
+  }
+  return { ...files, 'integrity.json': json(integrityBody) } as GeneratedArtifacts
+}
+
+export function iconAssets(index: ConsumerIndex): readonly PublishedAsset[] {
+  const assets = new Map<string, PublishedAsset>()
+  for (const product of Object.values(index.products)) {
+    if (!product.icon) continue
+    assets.set(product.icon.asset, publishedAssetOf(product.icon))
+  }
+  return [...assets.values()].toSorted((left, right) => left.name.localeCompare(right.name))
+}
+
+/**
+ * Publishes a verified artifact set to `generatedDirectory` under the output's
+ * coordination lock. See `catalog-store.ts` for the publication contract.
+ */
+export async function writeArtifacts(
+  generatedDirectory: string,
+  artifacts: GeneratedArtifacts,
+  options: PublishOptions = {}
+): Promise<void> {
+  await publishCatalog(generatedDirectory, artifacts as Record<string, string>, options)
+}
+
+function sortArtifactKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortArtifactKeys)
+  if (value !== null && typeof value === 'object')
+    return Object.fromEntries(
+      Object.keys(value as Record<string, unknown>)
+        .toSorted()
+        .map((key) => [key, sortArtifactKeys((value as Record<string, unknown>)[key])])
+    )
+  return value
+}
+
+function json(value: unknown): string {
+  return `${JSON.stringify(sortArtifactKeys(value), null, 2)}\n`
+}

package/src/build.ts

@@ -0,0 +1,131 @@
+import { mapWithConcurrency } from './concurrency.js'
+import { contentId } from './digest.js'
+import { normalizePlugin, type ReleaseOptions } from './plugin-release.js'
+import {
+  createSkippedPlugin,
+  PluginSafetyError,
+  UPSTREAM_WEATHER_SKIP_CODES,
+  type SkippedPlugin,
+} from './plugin-skips.js'
+import { assertRepositoryAllowed, DEFAULT_POLICY, type CatalogPolicy } from './policy.js'
+import {
+  CatalogSchema,
+  PluginSchema,
+  type Catalog,
+  type CatalogSource,
+  type Plugin,
+} from './schema.js'
+import type { ResolvedSource } from './source-resolution.js'
+import { canonicalRepositoryUrl } from './sources.js'
+import { orderLeadingPlugins } from './taxonomy.js'
+
+export interface BuildCatalogInput extends Omit<
+  ReleaseOptions,
+  'policy' | 'metadataOnly' | 'resolveExternalRefs'
+> {
+  readonly resolvedSources: readonly ResolvedSource[]
+  /** Each category's curated products, which head the catalog in this order. */
+  readonly leading?: Readonly<Record<string, readonly string[]>>
+  readonly policy?: CatalogPolicy
+  readonly metadataOnly?: boolean
+  readonly resolveExternalRefs?: boolean
+}
+
+interface BuildCatalogResult {
+  readonly catalog: Catalog
+  readonly skippedPlugins: readonly SkippedPlugin[]
+}
+
+export async function buildCatalog(input: BuildCatalogInput): Promise<Catalog> {
+  return (await buildCatalogInternal(input)).catalog
+}
+
+export async function buildCatalogInternal(input: BuildCatalogInput): Promise<BuildCatalogResult> {
+  const policy = input.policy ?? DEFAULT_POLICY
+  const options: ReleaseOptions = {
+    ...input,
+    policy,
+    metadataOnly: input.metadataOnly ?? false,
+    resolveExternalRefs: input.resolveExternalRefs ?? false,
+  }
+  for (const source of input.resolvedSources) {
+    assertRepositoryAllowed(source.config.repositoryUrl, policy)
+    for (const entry of source.parsed.entries) {
+      if (entry.source.kind === 'git') assertRepositoryAllowed(entry.source.repositoryUrl, policy)
+    }
+  }
+  const sourceRecords: CatalogSource[] = input.resolvedSources
+    .map(({ config, commitSha, retrievedAt, manifestDigest }) => ({
+      sourceId: config.sourceId,
+      displayName: config.displayName,
+      repositoryUrl: canonicalRepositoryUrl(config.repositoryUrl),
+      marketplaceDialect: config.marketplaceDialect,
+      manifestPath: config.manifestPath,
+      defaultBranch: config.defaultBranch,
+      resolvedCommitSha: commitSha,
+      retrievalTimestamp: retrievedAt,
+      trustClassification: config.trustClassification,
+      sourceManifestDigest: manifestDigest,
+      synchronizationStatus: 'synchronized' as const,
+    }))
+    .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId))
+  let plugins: Plugin[] = []
+  let skippedPlugins: SkippedPlugin[] = []
+  for (const source of input.resolvedSources) {
+    if (source.parsed.entries.length > policy.maxMarketplacePlugins)
+      throw new Error('MARKETPLACE_TOO_MANY_PLUGINS')
+    const normalized = await mapWithConcurrency(source.parsed.entries, 8, async (entry) => {
+      try {
+        const plugin = await normalizePlugin(source, entry, options)
+        try {
+          return { plugin: PluginSchema.parse(plugin) }
+        } catch {
+          throw new PluginSafetyError('PLUGIN_SCHEMA_INVALID', [])
+        }
+      } catch (error) {
+        const skipped = createSkippedPlugin(source, entry, error)
+        if (!skipped) throw error
+        return { skipped }
+      }
+    })
+    const sourcePlugins: Plugin[] = []
+    const sourceSkipped: SkippedPlugin[] = []
+    for (const result of normalized) {
+      if (result.plugin) sourcePlugins.push(result.plugin)
+      if (result.skipped) sourceSkipped.push(result.skipped)
+    }
+    const weatherSkips = sourceSkipped.filter((skipped) =>
+      UPSTREAM_WEATHER_SKIP_CODES.has(skipped.reasonCode)
+    )
+    if (source.parsed.entries.length > 0 && weatherSkips.length === source.parsed.entries.length)
+      throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [
+        canonicalRepositoryUrl(source.config.repositoryUrl),
+      ])
+    for (const plugin of sourcePlugins) plugins.push(plugin)
+    for (const skipped of sourceSkipped) skippedPlugins.push(skipped)
+  }
+  plugins = plugins.toSorted((left, right) => left.pluginId.localeCompare(right.pluginId))
+  skippedPlugins = skippedPlugins.toSorted(
+    (left, right) =>
+      left.pluginId.localeCompare(right.pluginId) ||
+      left.reasonCode.localeCompare(right.reasonCode) ||
+      left.paths.join('\0').localeCompare(right.paths.join('\0'))
+  )
+  const body = {
+    schemaVersion: 1 as const,
+    generatedAt:
+      sourceRecords
+        .map((s) => s.retrievalTimestamp)
+        .toSorted()
+        .at(-1) ?? new Date(0).toISOString(),
+    sources: sourceRecords,
+    plugins: orderLeadingPlugins({ plugins }, input.leading).plugins,
+  }
+  return {
+    catalog: CatalogSchema.parse({
+      ...body,
+      catalogId: contentId('catalog', body),
+    }),
+    skippedPlugins,
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,153 @@
+import { basename } from 'node:path'
+import { DEFAULT_POLICY, type CatalogPolicy } from './policy.js'
+import type { MarketplaceDialect } from './sources.js'
+import {
+  HarnessSchema,
+  type Capability,
+  type Harness,
+  type HarnessCompatibility,
+  type SecurityClassification,
+} from './schema.js'
+
+export function classifyCapabilities(
+  files: ReadonlyMap<string, Uint8Array>,
+  metadata?: Record<string, unknown>,
+  policy: CatalogPolicy = DEFAULT_POLICY
+): Capability[] {
+  const groups = new Map<string, string[]>()
+  const add = (type: Capability['type'], path: string) =>
+    groups.set(type, [...(groups.get(type) ?? []), path])
+  for (const path of files.keys()) {
+    const lower = path.toLocaleLowerCase()
+    const file = basename(lower)
+    if (file === 'skill.md' || lower.includes('/skills/')) add('skill', path)
+    if (file === '.mcp.json' || file === 'mcp.json' || lower.includes('/mcp-servers/'))
+      add('mcp-server', path)
+    if (lower.includes('/commands/') || lower.startsWith('commands/')) add('command', path)
+    if (lower.includes('/agents/') || lower.startsWith('agents/') || lower.includes('/subagents/'))
+      add('agent', path)
+    if (lower.includes('/hooks/') || lower.startsWith('hooks/') || file === 'hooks.json')
+      add('hook', path)
+    if (
+      lower.includes('/rules/') ||
+      lower.startsWith('rules/') ||
+      file === 'agents.md' ||
+      file === 'claude.md' ||
+      lower.includes('.cursor/rules/')
+    )
+      add('rule', path)
+    if (lower.includes('browser') || lower.includes('playwright') || lower.includes('chrome'))
+      add('browser', path)
+    if (lower.includes('/schedule') || lower.includes('/cron') || file.includes('schedule'))
+      add('scheduled-task', path)
+    if (lower.includes('/ui/') || lower.startsWith('ui/') || lower.includes('/components/'))
+      add('ui-component', path)
+    if (
+      lower.startsWith('bin/') ||
+      lower.startsWith('scripts/') ||
+      /\.(sh|bash|py|exe|bin)$/.test(file)
+    )
+      add('executable', path)
+  }
+  if (metadata && (metadata.mcpServers !== undefined || metadata.mcp !== undefined))
+    add('mcp-server', 'plugin-manifest')
+  if (metadata && (metadata.hooks !== undefined || metadata.hook !== undefined))
+    add('hook', 'plugin-manifest')
+  if (groups.size === 0) groups.set('unknown', ['plugin-root'])
+  return [...groups.entries()].map(([type, paths]) => ({
+    type: type as Capability['type'],
+    name: type,
+    paths: [...new Set(paths)].toSorted(),
+    metadata: {},
+    securityImpact: policy.sensitiveCapabilityTypes.includes(type) ? 'sensitive' : 'none',
+  }))
+}
+
+export function capabilitySummary(
+  capabilities: readonly Capability[]
+): Record<Capability['type'], number> {
+  const summary = {} as Record<Capability['type'], number>
+  for (const capability of capabilities) summary[capability.type] = capability.paths.length
+  return summary
+}
+
+export function createCompatibility(
+  dialect: MarketplaceDialect,
+  capabilities: readonly Capability[],
+  policy: CatalogPolicy = DEFAULT_POLICY
+): Record<Harness, HarnessCompatibility> {
+  const types = [...new Set(capabilities.map((capability) => capability.type))].toSorted()
+  const sensitive = types.filter((type) => policy.sensitiveCapabilityTypes.includes(type))
+  const make = (
+    status: HarnessCompatibility['status'],
+    reasons: string[]
+  ): HarnessCompatibility => ({
+    status,
+    reasons: [...new Set(reasons)].toSorted(),
+    responsibleCapabilities: types,
+  })
+  const result = {} as Record<Harness, HarnessCompatibility>
+  for (const harness of HarnessSchema.options) {
+    const native =
+      (harness === 'claude-code' && dialect === 'claude') ||
+      (harness === 'cursor' && dialect === 'cursor') ||
+      (harness === 'codex' && dialect === 'openai')
+    if (types.includes('executable'))
+      result[harness] = make('unsupported', [
+        'Executable components require harness-specific execution authority.',
+      ])
+    else if (types.includes('unknown'))
+      result[harness] = make('unknown', [
+        'The plugin content was not classified into a supported component type.',
+      ])
+    else if (native && sensitive.length === 0)
+      result[harness] = make('native', [
+        `The ${dialect} marketplace dialect matches the ${harness} harness.`,
+      ])
+    else if (sensitive.length > 0 && ['pi', 'hermes', 'opencode'].includes(harness))
+      result[harness] = make('partially-supported', [
+        `Sensitive capabilities require ${harness} policy and runtime review.`,
+        ...sensitive.map((type) => `Capability ${type} is not granted by this catalog.`),
+      ])
+    else if (
+      types.every((type) => ['skill', 'rule', 'mcp-server', 'command', 'agent'].includes(type))
+    )
+      result[harness] = make(
+        native ? 'native' : 'portable',
+        native
+          ? [`The ${dialect} marketplace dialect matches the ${harness} harness.`]
+          : ['Files can be copied or translated into the harness layout.']
+      )
+    else
+      result[harness] = make('requires-translation', [
+        'One or more capabilities need a harness-specific projection.',
+      ])
+  }
+  return result
+}
+
+export function createSecurity(
+  capabilities: readonly Capability[],
+  policy: CatalogPolicy,
+  metadataOnly: boolean
+): SecurityClassification {
+  const sensitive = [
+    ...new Set(
+      capabilities
+        .filter((capability) => policy.sensitiveCapabilityTypes.includes(capability.type))
+        .map((capability) => capability.type)
+    ),
+  ].toSorted()
+  const reasons =
+    sensitive.length > 0
+      ? sensitive.map((type) => `Contains ${type} capability metadata.`)
+      : metadataOnly
+        ? ['Content was not fetched in metadata-only mode.']
+        : ['No permission-sensitive executable capability was detected.']
+  return {
+    level: sensitive.length > 0 ? 'sensitive' : metadataOnly ? 'review' : 'low',
+    reasons,
+    permissionSensitiveChanges: sensitive,
+    contentResolution: metadataOnly ? 'metadata-only' : 'complete',
+  }
+}

package/src/catalog-store.ts

@@ -31,6 +31,7 @@ import { promises as fs } from 'node:fs'
 import { hostname } from 'node:os'
 import { basename, dirname, join, sep } from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
+import { writeDurably } from './fs-atomic.js'
 
 export type PublicationStep = 'acquiring' | 'staged' | 'backed-up' | 'swapped' | 'cleaned'
 
@@ -336,16 +337,6 @@ async function readJournal(paths: CatalogPaths): Promise<Journal | undefined> {
   throw new Error(`CATALOG_RECOVERY_REQUIRED: unrecognized journal ${paths.journal}`)
 }
 
-async function writeDurably(path: string, content: string | Uint8Array): Promise<void> {
-  const handle = await fs.open(path, 'wx')
-  try {
-    await handle.writeFile(content)
-    await handle.sync()
-  } finally {
-    await handle.close()
-  }
-}
-
 /** Best effort: directory fsync is unavailable on Windows and some filesystems. */
 async function syncDirectory(path: string): Promise<void> {
   let handle
@@ -526,21 +517,3 @@ export async function publishCatalog(
     await lock.release()
   }
 }
-
-/**
- * Writes one file so a reader sees either the old or the new bytes. For
- * content-addressed assets and the browsing index beside the catalog.
- */
-export async function writeFileAtomically(
-  path: string,
-  content: string | Uint8Array
-): Promise<void> {
-  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`)
-  try {
-    await writeDurably(temporary, content)
-    await fs.rename(temporary, path)
-  } catch (error) {
-    await fs.rm(temporary, { force: true })
-    throw error
-  }
-}

package/src/concurrency.ts

@@ -0,0 +1,19 @@
+export async function mapWithConcurrency<T, U>(
+  values: readonly T[],
+  concurrency: number,
+  mapper: (value: T, index: number) => Promise<U>
+): Promise<U[]> {
+  const results = Array.from<U>({ length: values.length })
+  let nextIndex = 0
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const index = nextIndex++
+      if (index >= values.length) return
+      results[index] = await mapper(values[index]!, index)
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(Math.max(concurrency, 1), values.length) }, () => worker())
+  )
+  return results
+}