Skip to content

A full-featured download manager.

10.6 KB
Raw Blame
// src/core/plugin/manifest/parse.ts

import { compareSemver } from '@shared/semver'
import { PluginEngineVersionTooOld, PluginManifestInvalid } from './errors'
import {
  type HookRole,
  isReservedPublisher,
  ManifestSchema,
  type ManifestZodOutput,
} from './schema'

const KNOWN_CONTRIBUTES_KEYS = [
  'commands',
  'hooks',
  'configuration',
  'operations',
] as const
const TYPO_DISTANCE_THRESHOLD = 2

// Spec §2 L331-345 — Phase 1A activation event vocabulary. Unknown tokens
// outside this set are forward-compat warnings, NOT errors (Phase 1B can
// introduce onSettingsOpen / onTaskComplete / onTaskError on existing v2.x
// hosts without making old hosts reject the new manifest).
const KNOWN_ACTIVATION_EVENT_LITERALS = new Set(['*', 'onStartup'])
const KNOWN_ACTIVATION_EVENT_PREFIXES = [
  'onCommand:',
  'onTaskType:',
  'onProtocol:',
] as const

function isKnownActivationEvent(token: string): boolean {
  if (KNOWN_ACTIVATION_EVENT_LITERALS.has(token)) return true
  return KNOWN_ACTIVATION_EVENT_PREFIXES.some(
    (p) => token.startsWith(p) && token.length > p.length
  )
}

export interface ParseManifestOptions {
  hostVersion: string
  // Builtins ship inside the app bundle and are allowed to claim reserved
  // publishers (motrix.*); community plugins discovered or installed at
  // runtime always default to 'community'.
  origin?: 'community' | 'builtin'
  /** Host-only result of checking the package against pinned official keys. */
  official?: boolean
}

export interface ManifestWarning {
  code: 'unknown-contributes-key' | 'unknown-activation-event'
  key: string
}

export interface ParseResult {
  manifest: ManifestZodOutput
  warnings: ManifestWarning[]
}

const STRICT_SEMVER_PATTERN =
  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/

interface EngineVersion {
  value: string
  core: [number, number, number]
  prerelease: boolean
}

export function semverSatisfies(version: string, range: string): boolean {
  if (range.trim() === '*') return true
  const host = parseVer(version, 'host_version_unparseable')
  const clauses = range
    .trim()
    .split(/\s+/)
    .map((clause) => {
      const match = /^(>=|<=|>|<|=|\^|~)?(.+)$/.exec(clause)
      if (!match) {
        throw new PluginManifestInvalid(
          'plugin.manifest.engines_unparseable',
          `unparseable range clause: ${clause}`
        )
      }
      return {
        op: match[1] ?? '=',
        target: parseVer(match[2], 'engines_unparseable'),
      }
    })
  // Existing plugins, including signed builtin seeds, use release-only ranges
  // to describe the host API line (e.g. >=2.0.0 <3.0.0 during the 2.0 beta).
  // Preserve that contract. An explicit prerelease in any clause opts the whole
  // range into full SemVer precedence, so a beta floor cannot be bypassed.
  const comparedVersion = clauses.some(({ target }) => target.prerelease)
    ? host.value
    : host.core.join('.')
  return clauses.every(({ op, target }) => {
    const cmp = compareSemver(comparedVersion, target.value)
    switch (op) {
      case '>=':
        return cmp >= 0
      case '<=':
        return cmp <= 0
      case '>':
        return cmp > 0
      case '<':
        return cmp < 0
      case '=':
        return cmp === 0
      case '^':
        return host.core[0] === target.core[0] && cmp >= 0
      case '~':
        return (
          host.core[0] === target.core[0] &&
          host.core[1] === target.core[1] &&
          cmp >= 0
        )
      default:
        return false
    }
  })
}

function parseVer(
  value: string,
  code: 'host_version_unparseable' | 'engines_unparseable'
): EngineVersion {
  const match = STRICT_SEMVER_PATTERN.exec(value)
  if (!match) {
    throw new PluginManifestInvalid(
      `plugin.manifest.${code}`,
      `unparseable version: ${value}`
    )
  }
  return {
    value,
    core: [Number(match[1]), Number(match[2]), Number(match[3])],
    prerelease: match[4] !== undefined,
  }
}

function levenshtein(a: string, b: string): number {
  const m = a.length
  const n = b.length
  if (m === 0) return n
  if (n === 0) return m
  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0))
  for (let i = 0; i <= m; i++) dp[i][0] = i
  for (let j = 0; j <= n; j++) dp[0][j] = j
  for (let i = 1; i <= m; i++) {
    for (let j = 1; j <= n; j++) {
      dp[i][j] =
        a[i - 1] === b[j - 1]
          ? dp[i - 1][j - 1]
          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
    }
  }
  return dp[m][n]
}

export function parseManifest(
  raw: string,
  opts: ParseManifestOptions
): ParseResult {
  let parsed: unknown
  try {
    parsed = JSON.parse(raw)
  } catch (e) {
    throw new PluginManifestInvalid(
      'plugin.manifest.invalid',
      `manifest is not valid JSON: ${(e as Error).message}`
    )
  }

  // Step 1: Read engines.motrix BEFORE strict schema validation.
  const enginesMotrix =
    typeof parsed === 'object' &&
    parsed !== null &&
    'engines' in parsed &&
    typeof (parsed as { engines: unknown }).engines === 'object' &&
    (parsed as { engines: { motrix?: unknown } }).engines !== null
      ? (parsed as { engines: { motrix?: unknown } }).engines.motrix
      : undefined
  if (typeof enginesMotrix === 'string') {
    if (!semverSatisfies(opts.hostVersion, enginesMotrix)) {
      throw new PluginEngineVersionTooOld(enginesMotrix, opts.hostVersion)
    }
  }

  // Step 2: Apply strict schema validation.
  const result = ManifestSchema.safeParse(parsed)
  if (!result.success) {
    throw new PluginManifestInvalid(
      'plugin.manifest.invalid',
      'manifest failed schema validation',
      result.error.issues
    )
  }

  // Step 3: Enforce reserved-publisher invariant. Community plugins must not
  // claim a reserved publisher (motrix.*, verified.*, official.*, system.*).
  // Official optional packages earn only the motrix.* namespace through
  // signature verification. Bundled builtins keep their separate origin gate.
  const origin = opts.origin ?? 'community'
  if (
    origin !== 'builtin' &&
    isReservedPublisher(result.data.id) &&
    !(opts.official && result.data.id.startsWith('motrix.'))
  ) {
    throw new PluginManifestInvalid(
      'plugin.manifest.id_reserved_publisher',
      `publisher name is reserved: "${result.data.id}"`,
      { manifestId: result.data.id }
    )
  }

  // Step 4: Enforce command-id namespace invariant — every contributed
  // command id must start with `<manifest.id>.` so cross-plugin invocations
  // can rely on the publisher prefix for routing/auth.
  const manifestId = result.data.id
  const commands = result.data.contributes.commands
  if (Array.isArray(commands)) {
    for (const cmd of commands) {
      if (!cmd.id.startsWith(`${manifestId}.`)) {
        throw new PluginManifestInvalid(
          'plugin.manifest.command.id_out_of_namespace',
          `contributes.commands[].id "${cmd.id}" must start with "${manifestId}."`,
          { commandId: cmd.id, manifestId }
        )
      }
    }
  }

  // Step 5: Typo detection vs forward-compat passthrough for contributes keys.
  const warnings: ManifestWarning[] = []
  const typos: Array<{ key: string; suggestion: string }> = []
  for (const k of Object.keys(result.data.contributes)) {
    if ((KNOWN_CONTRIBUTES_KEYS as readonly string[]).includes(k)) continue
    let bestKey = ''
    let bestDist = Infinity
    for (const cand of KNOWN_CONTRIBUTES_KEYS) {
      const d = levenshtein(k, cand)
      if (d < bestDist) {
        bestDist = d
        bestKey = cand
      }
    }
    if (bestDist > 0 && bestDist <= TYPO_DISTANCE_THRESHOLD) {
      typos.push({ key: k, suggestion: bestKey })
    } else {
      warnings.push({ code: 'unknown-contributes-key', key: k })
    }
  }
  if (typos.length > 0) {
    throw new PluginManifestInvalid(
      'plugin.manifest.contributes_key_typo',
      typos
        .map(
          (t) =>
            `"contributes.${t.key}" is unknown; did you mean "${t.suggestion}"?`
        )
        .join('\n'),
      typos
    )
  }

  // Step 6: Hook-driven invariants — both the role-eligibility rules
  // (spec §2 L569-577) and the host-permissions requirement (spec §2 L308-314
  // / §9.5 I29) need cross-field state (origin, categories, hostPermissions)
  // not available inside ManifestSchema, AND benefit from a specific error
  // code that the generic schema-wrapper at Step 2 would otherwise flatten.
  const hooks = result.data.contributes.hooks
  if (hooks && Object.keys(hooks).length > 0) {
    const hp = result.data.hostPermissions ?? []
    if (hp.length === 0) {
      throw new PluginManifestInvalid(
        'plugin.manifest.host_permissions_required_for_hooks',
        'declared hooks require at least one hostPermissions entry',
        { declaredHooks: Object.keys(hooks) }
      )
    }
  }
  if (hooks) {
    const categories = new Set(result.data.categories)
    for (const [hookName, entry] of Object.entries(hooks)) {
      if (!entry) continue
      const role = entry.role as HookRole
      if (role === 'pre-resolve' && origin !== 'builtin') {
        if (opts.official) {
          throw new PluginManifestInvalid(
            'plugin.install.official_builtin_hook',
            'plugin.install.official_builtin_hook'
          )
        }
        throw new PluginManifestInvalid(
          'plugin.manifest.role.requires_builtin',
          `contributes.hooks.${hookName}.role "pre-resolve" is reserved for built-in plugins`,
          { hook: hookName, role, origin }
        )
      }
      if (role === 'resolve' && !categories.has('site-resolver')) {
        throw new PluginManifestInvalid(
          'plugin.manifest.role.requires_category',
          `contributes.hooks.${hookName}.role "resolve" requires "site-resolver" in categories`,
          { hook: hookName, role, requiredCategory: 'site-resolver' }
        )
      }
      if (role === 'post-process' && !categories.has('post-action')) {
        throw new PluginManifestInvalid(
          'plugin.manifest.role.requires_category',
          `contributes.hooks.${hookName}.role "post-process" requires "post-action" in categories`,
          { hook: hookName, role, requiredCategory: 'post-action' }
        )
      }
    }
  }

  // Step 7: Unknown activation events — forward-compat warning, NOT error
  // (spec §2 L343). v2.5 plugins declaring `onSettingsOpen` install fine on
  // v2.0 hosts; they just won't activate on that token.
  for (const token of result.data.activationEvents) {
    if (!isKnownActivationEvent(token)) {
      warnings.push({ code: 'unknown-activation-event', key: token })
    }
  }

  return { manifest: result.data, warnings }
}