@meith/marketplace 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/marketplace",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,6 +19,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/theme-kit": "0.21.1"
+    "@meith/theme-kit": "0.22.0"
   }
 }

package/src/build-info.ts

@@ -1,27 +1,7 @@
 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.21.1'
+export const MEITH_VERSION = '0.22.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

@@ -2,8 +2,6 @@ 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
@@ -18,18 +16,6 @@ export const EMPTY_CACHE: CachedMarketplace = {
   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`).
- * `claimNotified` is what makes an update notify administrators exactly once
- * per (plugin, version), ever, even when the daily task and an admin's
- * "Refresh" click race on the same newly-seen version — 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). See
- * docs/marketplace.md for why the claim is a single atomic step rather than
- * a check followed by a write.
- */
 export interface MarketplaceCacheRepository {
   read(): Promise<CachedMarketplace>
   saveFeed(input: {
@@ -38,10 +24,5 @@ export interface MarketplaceCacheRepository {
     readonly fetchedAt: Date
   }): Promise<void>
   saveError(input: { readonly message: string; readonly at: Date }): Promise<void>
-  /**
-   * Atomically records (key, version) as notified and reports whether this
-   * call is the one that newly claimed it — `false` means some other caller
-   * (a concurrent refresh) already has, and this one must not notify.
-   */
   claimNotified(key: string, version: string): Promise<boolean>
 }

package/src/fetch.ts

@@ -1,14 +1,6 @@
-/**
- * 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
 }
 
@@ -18,11 +10,9 @@ 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
 }
 
-/** See `docs/marketplace.md#outbound-fetches-do-not-follow-redirects`. */
 export async function readCappedBody(
   response: Response,
   maxBytes: number,
@@ -62,14 +52,6 @@ export async function readCappedBody(
   return combined
 }
 
-/**
- * Fetches and JSON-parses a marketplace feed. Never throws: an unreachable
- * host, a non-200 response (a redirect included — see
- * `docs/marketplace.md#outbound-fetches-do-not-follow-redirects`), 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()

package/src/range.ts

@@ -1,25 +1,3 @@
-/**
- * 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+)$/
@@ -39,7 +17,6 @@ function compareParts(a: readonly number[], b: readonly number[]): number {
   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)
@@ -69,7 +46,6 @@ function parseComparator(token: string): Comparator | null {
   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
@@ -101,11 +77,6 @@ function satisfiesComparator(comparator: Comparator, version: Semver): boolean {
   }
 }
 
-/**
- * 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

package/src/refresh.ts

@@ -8,13 +8,7 @@ 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, after it has
-   * already been claimed as notified — see docs/marketplace.md for why the
-   * claim happens first, and what that means if this throws.
-   */
   readonly notifyUpdate: (listing: MarketplaceListing) => Promise<void>
   readonly now?: () => Date
   readonly fetchImpl?: typeof fetch
@@ -28,15 +22,6 @@ export interface RefreshCatalogResult {
   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, and
- * the two can run concurrently: `claimNotified` is what keeps a race between
- * them from raising the same (plugin, version) update twice.
- */
 export async function refreshCatalog(input: RefreshCatalogInput): Promise<RefreshCatalogResult> {
   const now = input.now ?? (() => new Date())
 

package/src/schema.ts

@@ -1,22 +1,3 @@
-/**
- * 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 {
@@ -52,15 +33,9 @@ export const REQUIRED_LISTING_FIELDS = [
   'licence',
 ] as const
 
-/**
- * Mirrors KEY_PATTERN in scripts/marketplace-gen.mjs and
- * packages/plugin-kit/src/plugin.ts. Exported so
- * scripts/marketplace-gen.test.ts can pin all three against each other.
- */
 export 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 this file's own header. */
 const SCREENSHOT_PATH_PATTERN = /^\/marketplace\/screenshots\/[a-z0-9][a-z0-9-]*\.png$/
 const KINDS = new Set<string>(['plugin', 'theme'])
 
@@ -148,12 +123,6 @@ function validateListing(entry: unknown, index: number): readonly string[] {
   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'] }

package/src/status.ts

@@ -16,21 +16,16 @@ export interface CompatibilityCheck {
 }
 
 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,
@@ -54,10 +49,8 @@ export function checkCompatibility(
   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
 }
 
@@ -67,25 +60,9 @@ export interface ListingStatusInput extends CompatibilityCheck {
 
 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,