@meith/marketplace 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@meith/marketplace",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/marketplace"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/theme-kit": "0.16.0"
+  }
+}

package/src/build-info.ts

@@ -0,0 +1,27 @@
+import { parseApiVersion, THEME_API_VERSION } from '@meith/theme-kit'
+
+/**
+ * This board's own release version, checked against a listing's `meith`
+ * range. Duplicated the same way `CODE_VERSION` already is across
+ * apps/cli/src/upgrade.ts, apps/community/src/server/upgrade-notice.ts and
+ * packages/create-meith/src/bin.ts — see docs/release.md — and kept honest
+ * by the same `scripts/release-check.mjs`.
+ */
+export const MEITH_VERSION = '0.16.0'
+
+/**
+ * The theme-kit major this build implements, read from the single place
+ * that already declares it rather than duplicated as a literal.
+ */
+export const THEME_API_MAJOR = parseApiVersion(THEME_API_VERSION).major
+
+/**
+ * The plugin-kit major this build implements. Unlike theme-kit, plugin-kit
+ * exports no equivalent constant — a plugin's own `apiVersion` is a free
+ * string nothing currently checks (see docs/plugin-api.md's Versioning
+ * section, which describes the policy without a constant enforcing it).
+ * Both kits are pre-1.0, so this is 0 until plugin-kit ships a major of its
+ * own; bump it by hand alongside that, the same way this file's other
+ * constant is bumped by hand at every release.
+ */
+export const PLUGIN_API_MAJOR = 0

package/src/cache.ts

@@ -0,0 +1,40 @@
+import type { MarketplaceFeed } from './schema'
+
+export interface CachedMarketplace {
+  readonly feed: MarketplaceFeed | null
+  /** The feed URL `feed` was actually fetched from — a listing's screenshot
+   *  path is resolved against this, not against today's setting. */
+  readonly sourceUrl: string | null
+  readonly fetchedAt: Date | null
+  readonly error: string | null
+  readonly errorAt: Date | null
+}
+
+export const EMPTY_CACHE: CachedMarketplace = {
+  feed: null,
+  sourceUrl: null,
+  fetchedAt: null,
+  error: null,
+  errorAt: null,
+}
+
+/**
+ * The cached feed and the daily task's own bookkeeping — one row, whichever
+ * infrastructure package backs it (see packages/db's `marketplace-repo.ts`).
+ * `hasNotified`/`markNotified` are what make an update notify administrators
+ * exactly once per (plugin, version), ever: independent of whether the
+ * notification itself has since been read, which a bare `dedupeKey` on the
+ * notification service is not (its coalescing only holds while a
+ * notification is unread — see packages/notifications).
+ */
+export interface MarketplaceCacheRepository {
+  read(): Promise<CachedMarketplace>
+  saveFeed(input: {
+    readonly feed: MarketplaceFeed
+    readonly sourceUrl: string
+    readonly fetchedAt: Date
+  }): Promise<void>
+  saveError(input: { readonly message: string; readonly at: Date }): Promise<void>
+  hasNotified(key: string, version: string): Promise<boolean>
+  markNotified(key: string, version: string): Promise<void>
+}

package/src/fetch.ts

@@ -0,0 +1,68 @@
+/**
+ * The one place this package touches the network — and only ever server-side:
+ * the daily task and the admin "Refresh" action both call `refreshCatalog`
+ * (see refresh.ts), never the browser. Node's built-in `fetch` is enough; no
+ * HTTP client dependency is added for this.
+ */
+export interface FetchFeedResult {
+  readonly ok: boolean
+  /** Parsed JSON body, present only when `ok` is true. */
+  readonly body: unknown
+  /** A short, loggable reason, present only when `ok` is false. */
+  readonly error: string | null
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000
+const MAX_BODY_BYTES = 2_000_000
+
+export interface FetchFeedOptions {
+  readonly url: string
+  readonly timeoutMs?: number
+  /** Swappable for tests; defaults to the platform's global `fetch`. */
+  readonly fetchImpl?: typeof fetch
+}
+
+/**
+ * Fetches and JSON-parses a marketplace feed. Never throws: an unreachable
+ * host, a non-200 response, an oversized body or invalid JSON are all
+ * reported as `{ ok: false, error }` — the board with no outbound network is
+ * meant to fail quietly here, not crash the task that called this.
+ */
+export async function fetchMarketplaceFeed(options: FetchFeedOptions): Promise<FetchFeedResult> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+
+  try {
+    let response: Response
+    try {
+      response = await fetchImpl(options.url, {
+        signal: controller.signal,
+        headers: { accept: 'application/json' },
+      })
+    } catch (error) {
+      return { ok: false, body: null, error: `could not reach ${options.url}: ${String(error)}` }
+    }
+
+    if (!response.ok) {
+      return { ok: false, body: null, error: `${options.url} answered ${response.status}` }
+    }
+
+    const text = await response.text()
+    if (text.length > MAX_BODY_BYTES) {
+      return {
+        ok: false,
+        body: null,
+        error: `${options.url} answered a body over ${MAX_BODY_BYTES} bytes`,
+      }
+    }
+
+    try {
+      return { ok: true, body: JSON.parse(text), error: null }
+    } catch {
+      return { ok: false, body: null, error: `${options.url} did not answer valid JSON` }
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export { MEITH_VERSION, PLUGIN_API_MAJOR, THEME_API_MAJOR } from './build-info'
+export { type CachedMarketplace, EMPTY_CACHE, type MarketplaceCacheRepository } from './cache'
+export { type FetchFeedOptions, type FetchFeedResult, fetchMarketplaceFeed } from './fetch'
+export {
+  compareSemver,
+  parseMeithRange,
+  parseSemver,
+  type Semver,
+  satisfiesMeithRange,
+} from './range'
+export { type RefreshCatalogInput, type RefreshCatalogResult, refreshCatalog } from './refresh'
+export {
+  type FeedValidation,
+  type ListingKind,
+  type MarketplaceFeed,
+  type MarketplaceListing,
+  REQUIRED_LISTING_FIELDS,
+  validateFeed,
+} from './schema'
+export {
+  type BuildInfo,
+  type CompatibilityCheck,
+  type CompatibilityResult,
+  checkCompatibility,
+  computeListingStatus,
+  type InstalledEntry,
+  type ListingStatus,
+  type ListingStatusInput,
+  type ListingStatusResult,
+} from './status'

package/src/range.ts

@@ -0,0 +1,117 @@
+/**
+ * Version comparison and the "meith" range check.
+ *
+ * `marketplace/schema.json` documents the range syntax but the generator
+ * only checks that it *parses* — it is never evaluated against a real
+ * version there (see docs/marketplace.md). This is that evaluation, written
+ * for the first time here: comparators `>=`, `<=`, `>`, `<` or `=` (default
+ * `=`) against a version of one to three numeric parts, space-separated to
+ * mean AND.
+ *
+ * Precision is handled differently for the two families, which is a
+ * deliberate reading rather than something the docs pin down:
+ *
+ * - `=` **truncates** the board version to the comparator's own precision,
+ *   so `=1` means "meith major 1, whatever the minor and patch" and `=1.2`
+ *   means "1.2.x". That is what "pin to a major or minor" has to mean.
+ * - `>=`, `<=`, `>`, `<` **zero-pad** the comparator to three parts before
+ *   comparing the full version against it, so `<1` means "strictly before
+ *   1.0.0" and `>1.2` means "newer than 1.2.0" (1.2.5 included) rather than
+ *   "1.3.0 or later". That is the ordinary meaning of a version bound.
+ */
+
+export type Semver = readonly [number, number, number]
+
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/
+
+export function parseSemver(value: string): Semver | null {
+  const match = SEMVER_PATTERN.exec(value.trim())
+  if (match === null) return null
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+function compareParts(a: readonly number[], b: readonly number[]): number {
+  const length = Math.max(a.length, b.length)
+  for (let i = 0; i < length; i += 1) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0)
+    if (diff !== 0) return Math.sign(diff)
+  }
+  return 0
+}
+
+/** -1 if `a` is older than `b`, 0 if equal, 1 if newer. Both must be full semver. */
+export function compareSemver(a: string, b: string): number {
+  const left = parseSemver(a)
+  const right = parseSemver(b)
+  if (left === null || right === null) {
+    throw new Error(`marketplace: "${left === null ? a : b}" is not a major.minor.patch version`)
+  }
+  return compareParts(left, right)
+}
+
+type ComparatorOp = '>=' | '<=' | '>' | '<' | '='
+
+interface Comparator {
+  readonly op: ComparatorOp
+  readonly parts: readonly number[]
+}
+
+const COMPARATOR_TOKEN = /^(>=|<=|>|<|=)?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/
+
+function parseComparator(token: string): Comparator | null {
+  const match = COMPARATOR_TOKEN.exec(token)
+  if (match === null) return null
+
+  const op = (match[1] ?? '=') as ComparatorOp
+  const parts = [match[2], match[3], match[4]]
+    .filter((part): part is string => part !== undefined)
+    .map(Number)
+  return { op, parts }
+}
+
+/** Parses a `meith` range string, or null when it does not parse. */
+export function parseMeithRange(range: string): readonly Comparator[] | null {
+  const trimmed = range.trim()
+  if (trimmed === '') return null
+
+  const comparators = trimmed.split(/\s+/).map(parseComparator)
+  return comparators.every((c): c is Comparator => c !== null) ? comparators : null
+}
+
+function satisfiesComparator(comparator: Comparator, version: Semver): boolean {
+  if (comparator.op === '=') {
+    return compareParts(version.slice(0, comparator.parts.length), comparator.parts) === 0
+  }
+
+  const padded: Semver = [
+    comparator.parts[0] ?? 0,
+    comparator.parts[1] ?? 0,
+    comparator.parts[2] ?? 0,
+  ]
+  const cmp = compareParts(version, padded)
+  switch (comparator.op) {
+    case '>=':
+      return cmp >= 0
+    case '<=':
+      return cmp <= 0
+    case '>':
+      return cmp > 0
+    case '<':
+      return cmp < 0
+  }
+}
+
+/**
+ * Whether `version` (major.minor.patch) satisfies every comparator in
+ * `range`. An unparseable range or version is never satisfied — an honest
+ * "no", not a thrown error, since this runs against untrusted feed data.
+ */
+export function satisfiesMeithRange(range: string, version: string): boolean {
+  const comparators = parseMeithRange(range)
+  if (comparators === null) return false
+
+  const parsedVersion = parseSemver(version)
+  if (parsedVersion === null) return false
+
+  return comparators.every((comparator) => satisfiesComparator(comparator, parsedVersion))
+}

package/src/refresh.ts

@@ -0,0 +1,73 @@
+import type { MarketplaceCacheRepository } from './cache'
+import { fetchMarketplaceFeed } from './fetch'
+import type { MarketplaceListing } from './schema'
+import { validateFeed } from './schema'
+import { type BuildInfo, computeListingStatus, type InstalledEntry } from './status'
+
+export interface RefreshCatalogInput {
+  readonly url: string
+  readonly repository: MarketplaceCacheRepository
+  readonly build: BuildInfo
+  /** How this build resolves a listing's key against what it compiled in. */
+  readonly resolveInstalled: (listing: MarketplaceListing) => InstalledEntry | null
+  /** Called once per newly-detected (plugin, version) update, before it is recorded as notified. */
+  readonly notifyUpdate: (listing: MarketplaceListing) => Promise<void>
+  readonly now?: () => Date
+  readonly fetchImpl?: typeof fetch
+  readonly timeoutMs?: number
+}
+
+export interface RefreshCatalogResult {
+  readonly ok: boolean
+  readonly listingCount: number
+  readonly notified: number
+  readonly error: string | null
+}
+
+/**
+ * Fetches, validates and caches the feed, then raises the update
+ * notification for any plugin whose new version this board has not already
+ * notified about. This is the one function both the daily task and the
+ * admin "Refresh" button call — see docs/marketplace.md — so there is
+ * exactly one place that decides what counts as a successful refresh.
+ */
+export async function refreshCatalog(input: RefreshCatalogInput): Promise<RefreshCatalogResult> {
+  const now = input.now ?? (() => new Date())
+
+  const fetched = await fetchMarketplaceFeed({
+    url: input.url,
+    ...(input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+    ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+  })
+
+  if (!fetched.ok) {
+    const message = fetched.error ?? 'unknown fetch error'
+    await input.repository.saveError({ message, at: now() })
+    return { ok: false, listingCount: 0, notified: 0, error: message }
+  }
+
+  const validated = validateFeed(fetched.body)
+  if (!validated.ok) {
+    const message = `feed failed validation: ${validated.errors.slice(0, 5).join('; ')}`
+    await input.repository.saveError({ message, at: now() })
+    return { ok: false, listingCount: 0, notified: 0, error: message }
+  }
+
+  await input.repository.saveFeed({ feed: validated.feed, sourceUrl: input.url, fetchedAt: now() })
+
+  let notified = 0
+  for (const listing of validated.feed.listings) {
+    if (listing.kind !== 'plugin') continue
+
+    const installed = input.resolveInstalled(listing)
+    const result = computeListingStatus({ ...listing, installed }, input.build)
+    if (result.status !== 'update-available') continue
+    if (await input.repository.hasNotified(listing.key, listing.version)) continue
+
+    await input.notifyUpdate(listing)
+    await input.repository.markNotified(listing.key, listing.version)
+    notified += 1
+  }
+
+  return { ok: true, listingCount: validated.feed.listings.length, notified, error: null }
+}

package/src/schema.ts

@@ -0,0 +1,172 @@
+/**
+ * The shape of a listing on the wire — mirroring `marketplace/schema.json`
+ * and `scripts/marketplace-gen.mjs`, which this package never imports (a
+ * board-side consumer and the generator that produces the feed it consumes
+ * are deliberately separate concerns; see docs/marketplace.md). One
+ * difference is load-bearing: `marketplace/schema.json` validates a
+ * *listing file* before it is merged, where `screenshots` is a bare
+ * filename. What a board actually fetches is the *emitted* feed at
+ * `/marketplace/v1.json`, where `buildFeed()` has already rewritten every
+ * screenshot into an absolute site path (`/marketplace/screenshots/x.png`)
+ * and wrapped the listings in `{ schema, listings }`. `validateFeed` below
+ * validates that served shape — same fields, same rules, screenshots
+ * checked as paths rather than bare names — which is "the same schema
+ * shape" the issue asks for once the wrapper and the path rewrite are
+ * accounted for. `packages/marketplace/src/schema.test.ts` cross-checks the
+ * required field list against `marketplace/schema.json` itself so the two
+ * cannot silently drift apart.
+ */
+
+export type ListingKind = 'plugin' | 'theme'
+
+export interface MarketplaceListing {
+  readonly key: string
+  readonly kind: ListingKind
+  readonly package: string
+  readonly name: string
+  readonly description: string
+  readonly screenshots: readonly string[]
+  readonly version: string
+  readonly apiVersion: number
+  readonly meith: string
+  readonly repository: string
+  readonly licence: string
+}
+
+export interface MarketplaceFeed {
+  readonly schema: string
+  readonly listings: readonly MarketplaceListing[]
+}
+
+export const REQUIRED_LISTING_FIELDS = [
+  'key',
+  'kind',
+  'package',
+  'name',
+  'description',
+  'screenshots',
+  'version',
+  'apiVersion',
+  'meith',
+  'repository',
+  'licence',
+] as const
+
+const KEY_PATTERN = /^[a-z][a-z0-9-]{1,39}$/
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/
+const PACKAGE_PATTERN = /^(@[a-z0-9-][a-z0-9-._]*\/)?[a-z0-9-][a-z0-9-._]*$/
+// The served feed's screenshots are absolute site paths, not bare filenames —
+// see the module comment above.
+const SCREENSHOT_PATH_PATTERN = /^\/marketplace\/screenshots\/[a-z0-9][a-z0-9-]*\.png$/
+const KINDS = new Set<string>(['plugin', 'theme'])
+
+export type FeedValidation =
+  | { readonly ok: true; readonly feed: MarketplaceFeed; readonly errors: readonly [] }
+  | { readonly ok: false; readonly feed: null; readonly errors: readonly string[] }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function validateListing(entry: unknown, index: number): readonly string[] {
+  const where = `listings[${index}]`
+  if (!isRecord(entry)) return [`${where}: a listing must be an object`]
+
+  const errors: string[] = []
+  for (const field of REQUIRED_LISTING_FIELDS) {
+    if (!(field in entry)) errors.push(`${where}: missing field "${field}"`)
+  }
+  for (const field of Object.keys(entry)) {
+    if (!(REQUIRED_LISTING_FIELDS as readonly string[]).includes(field)) {
+      errors.push(`${where}: unexpected field "${field}"`)
+    }
+  }
+
+  if ('key' in entry && (typeof entry.key !== 'string' || !KEY_PATTERN.test(entry.key))) {
+    errors.push(`${where}: "key" is not lower-case letters, digits and hyphens`)
+  }
+  if ('kind' in entry && (typeof entry.kind !== 'string' || !KINDS.has(entry.kind))) {
+    errors.push(`${where}: "kind" must be "plugin" or "theme"`)
+  }
+  if (
+    'package' in entry &&
+    (typeof entry.package !== 'string' || !PACKAGE_PATTERN.test(entry.package))
+  ) {
+    errors.push(`${where}: "package" is not a valid npm package name`)
+  }
+  if ('name' in entry && (typeof entry.name !== 'string' || entry.name.trim() === '')) {
+    errors.push(`${where}: "name" must not be empty`)
+  }
+  if (
+    'description' in entry &&
+    (typeof entry.description !== 'string' || entry.description.trim() === '')
+  ) {
+    errors.push(`${where}: "description" must not be empty`)
+  }
+  if ('screenshots' in entry) {
+    if (!Array.isArray(entry.screenshots) || entry.screenshots.length === 0) {
+      errors.push(`${where}: "screenshots" must be a non-empty array`)
+    } else if (
+      !entry.screenshots.every(
+        (shot) => typeof shot === 'string' && SCREENSHOT_PATH_PATTERN.test(shot),
+      )
+    ) {
+      errors.push(
+        `${where}: "screenshots" has an entry that is not a /marketplace/screenshots/*.png path`,
+      )
+    }
+  }
+  if (
+    'version' in entry &&
+    (typeof entry.version !== 'string' || !VERSION_PATTERN.test(entry.version))
+  ) {
+    errors.push(`${where}: "version" must be major.minor.patch`)
+  }
+  if (
+    'apiVersion' in entry &&
+    (!Number.isInteger(entry.apiVersion) || (entry.apiVersion as number) < 0)
+  ) {
+    errors.push(`${where}: "apiVersion" must be a non-negative integer`)
+  }
+  if ('meith' in entry && typeof entry.meith !== 'string') {
+    errors.push(`${where}: "meith" must be a string range`)
+  }
+  if (
+    'repository' in entry &&
+    (typeof entry.repository !== 'string' || !/^https:\/\//.test(entry.repository))
+  ) {
+    errors.push(`${where}: "repository" must be an https URL`)
+  }
+  if ('licence' in entry && (typeof entry.licence !== 'string' || entry.licence.trim() === '')) {
+    errors.push(`${where}: "licence" must not be empty`)
+  }
+
+  return errors
+}
+
+/**
+ * Validates the document a board fetches from `/marketplace/v1.json` (or a
+ * self-hosted mirror of it) against the same shape MEI-79's schema defines.
+ * Never throws — a malformed feed is exactly the case this function exists
+ * to report, not to crash the fetch task over.
+ */
+export function validateFeed(raw: unknown): FeedValidation {
+  if (!isRecord(raw)) {
+    return { ok: false, feed: null, errors: ['the feed must be a JSON object'] }
+  }
+  if (typeof raw.schema !== 'string' || raw.schema === '') {
+    return { ok: false, feed: null, errors: ['the feed has no "schema" field'] }
+  }
+  if (!Array.isArray(raw.listings)) {
+    return { ok: false, feed: null, errors: ['the feed has no "listings" array'] }
+  }
+
+  const errors = raw.listings.flatMap((entry, index) => validateListing(entry, index))
+  if (errors.length > 0) return { ok: false, feed: null, errors }
+
+  return {
+    ok: true,
+    feed: { schema: raw.schema, listings: raw.listings as MarketplaceListing[] },
+    errors: [],
+  }
+}

package/src/status.ts

@@ -0,0 +1,114 @@
+import { compareSemver, satisfiesMeithRange } from './range'
+import type { ListingKind } from './schema'
+
+export type ListingStatus =
+  | 'active'
+  | 'installed-disabled'
+  | 'not-installed'
+  | 'update-available'
+  | 'incompatible'
+
+export interface CompatibilityCheck {
+  readonly kind: ListingKind
+  readonly version: string
+  readonly apiVersion: number
+  readonly meith: string
+}
+
+export interface BuildInfo {
+  /** This board's own release version — `CODE_VERSION`, checked against `meith`. */
+  readonly meithVersion: string
+  /** The plugin-kit major this build implements, checked against a plugin listing's `apiVersion`. */
+  readonly pluginApiMajor: number
+  /** The theme-kit major this build implements, checked against a theme listing's `apiVersion`. */
+  readonly themeApiMajor: number
+}
+
+export interface CompatibilityResult {
+  readonly compatible: boolean
+  /** Set exactly when `compatible` is false — why, in words a board operator can act on. */
+  readonly reason: string | null
+}
+
+/** Checks a listing's declared `apiVersion` and `meith` range against this build. */
+export function checkCompatibility(
+  listing: CompatibilityCheck,
+  build: BuildInfo,
+): CompatibilityResult {
+  const wantedMajor = listing.kind === 'plugin' ? build.pluginApiMajor : build.themeApiMajor
+  const apiOk = listing.apiVersion === wantedMajor
+  const meithOk = satisfiesMeithRange(listing.meith, build.meithVersion)
+
+  if (apiOk && meithOk) return { compatible: true, reason: null }
+
+  const reasons: string[] = []
+  if (!apiOk) {
+    reasons.push(
+      `built against ${listing.kind === 'plugin' ? 'plugin' : 'theme'}-kit major ${listing.apiVersion}, ` +
+        `this board runs major ${wantedMajor}`,
+    )
+  }
+  if (!meithOk) {
+    reasons.push(`needs meith ${listing.meith}, this board runs ${build.meithVersion}`)
+  }
+  return { compatible: false, reason: reasons.join('; ') }
+}
+
+/** What this build already knows about a listing's key, if anything. */
+export interface InstalledEntry {
+  readonly enabled: boolean
+  /** The compiled version to compare the feed against, or null when there is none to compare. */
+  readonly version: string | null
+}
+
+export interface ListingStatusInput extends CompatibilityCheck {
+  readonly installed: InstalledEntry | null
+}
+
+export interface ListingStatusResult {
+  readonly status: ListingStatus
+  /** Set exactly when `status` is 'incompatible'. */
+  readonly incompatibleReason: string | null
+}
+
+/**
+ * The five statuses the Browse tab renders, computed against what this build
+ * actually contains — never against what installing would do, because this
+ * screen does not install anything.
+ *
+ * An installed plugin or theme that is merely *running* is never recomputed
+ * to 'incompatible' on the strength of the catalog's opinion of its current
+ * listing — what is already active keeps being reported as active. Incompat-
+ * ibility only gates two things: a listing nothing has installed, and an
+ * update this board would otherwise offer. That is also why a theme (whose
+ * compiled version this build cannot see — `defineTheme` carries none) never
+ * reports 'update-available': there is nothing reliable to compare against,
+ * so it settles on active/disabled once compatibility has been read for the
+ * not-installed case.
+ */
+export function computeListingStatus(
+  input: ListingStatusInput,
+  build: BuildInfo,
+): ListingStatusResult {
+  const compatibility = checkCompatibility(input, build)
+
+  if (input.installed === null) {
+    return compatibility.compatible
+      ? { status: 'not-installed', incompatibleReason: null }
+      : { status: 'incompatible', incompatibleReason: compatibility.reason }
+  }
+
+  const hasNewerListedVersion =
+    input.installed.version !== null && compareSemver(input.version, input.installed.version) > 0
+
+  if (hasNewerListedVersion) {
+    return compatibility.compatible
+      ? { status: 'update-available', incompatibleReason: null }
+      : { status: 'incompatible', incompatibleReason: compatibility.reason }
+  }
+
+  return {
+    status: input.installed.enabled ? 'active' : 'installed-disabled',
+    incompatibleReason: null,
+  }
+}