Static plugin registry metadata for Lapis Notes.
The V2 registry publishes inline-signed JSON metadata using the API's shared
presentation schema. generated/v2/ is the current catalog;
generated/v1/ remains a signed archive. Official plugins publish deterministic,
per-package-version GitHub archives and npm packages for static composition.
The Astro site renders descriptions, highlights, documentation links, themed logos/banner/overview/gallery images and structured per-version changelogs. V2 omits README and Markdown-reference fields. Immutable artifact hashes and compatibility data remain attached to each version; listing compatibility comes from the latest release. Nostr deployment remains deferred.
plugin_release dispatches verify signatures, artifact hashes and pinned source
metadata before opening idempotent one-file submission PRs. Merging a submission
queues it; one Publish registry updates PR combines approved requests and
updates the entries, mirrored images, generated catalog and signatures together.
Preparation uploads an immutable qualified candidate before a separate writer
publishes it. Failed publication resumes that artifact without repeating builds
or signing; identical qualified batches create no new writes. See the
qualification and recovery contract.
Metadata-only dispatches retain
release artifacts and version history. Source schema V1 remains readable for
older independent plugins; publication normalizes to V2. Structured notes use
the exact Changesets section or a validated
registry.json.releases[version].changelog override.
The first signed V2 cutover requires approval. After
STATIC_REGISTRY_V2_DEPLOY_APPROVED is enabled, validated publication merges to main deploy
the Astro site and signed catalog. Signing remains a protected, reviewable step
using the existing registry and release trust roots.
The V2 contract is owned by @lapis-notes/api/registry/schema and requires
API 0.1.1 or newer. Community publication is not a prerequisite. Before that
API release is published, local acceptance uses an ignored checksum-pinned API
tarball hook. Keep the tracked dependency on its npm semver range; refresh the
registry lockfile from npm once that release is available. A temporary tarball
install does not qualify the production frozen-install gate.
pnpm install
pnpm check
pnpm registry:validate
pnpm registry:submissions:verify
pnpm registry:sync:github -- --event-path /path/to/repository-dispatch.json --dry-run
pnpm registry:preview:release-plan -- --release-plan ../lapis-plugins/.release/release-plan.json --public-key ../lapis-plugins/.release/plugin-release-public.pem --output tmp/registry-preview.json
pnpm registry:generate
pnpm registry:verify-signatures
pnpm stats:validate
pnpm site:dev:source
pnpm test:browsersite:dev:source starts the catalog with an unsigned overlay from the sibling
../lapis-plugins checkout. It reads current package manifests,
registry.json, presentation fields, release notes, logos, and gallery assets without
changing the signed generated catalog or its signatures. A banner keeps the local preview
distinct from signed production metadata. Point it at another checkout or port
when needed:
pnpm site:dev:source -- --source ../lapis-plugins-registry-media --port 4322Each port uses an isolated temporary overlay, so a browser test server or a
second working-source preview cannot remove another preview's assets. The
helper binds to 127.0.0.1 by default so its generated media URLs and review
address use the same reachable host.
Source packages absent from the curated catalog appear as pending entries only in this local overlay. Their bundles cannot be installed. Slides appears until its first approved release is indexed. Private/parked Community source is excluded from the overlay.
Gallery cards use an atomic responsive-image contract. Source metadata declares one to five cards with optional 1200×800 preview and 2400×1600 full/light/dark lossless-WebP paths, plus source-only Storybook capture and colour-segmented headline and description composition instructions. Published detail metadata retains only each card's ID, alternative text, and authored hashed image variants. Display fallbacks preserve missing authored variants.
Registry signing uses protected CI secrets or a local key generated under
~/.lapis/:
pnpm registry:keygen
LAPIS_REGISTRY_KEY_ID=lapis-registry-2026-01 \
LAPIS_REGISTRY_PRIVATE_KEY_PEM_B64="$(base64 -i ~/.lapis/lapis-registry-private.pem | tr -d '\n')" \
pnpm registry:signPrivate keys must never be committed. V2 metadata must be signed with the existing registry key before cutover. Tests generate isolated ephemeral keys and output directories, separate from production build output.
entries/**: human-maintained JSONC source entries.schemas/**: strict JSON schemas for source and generated metadata.generated/v2/**: deterministic current registry files with inline signatures plus matching signature sidecars.generated/v1/**: retained archive for older clients.stats/daily/**: immutable UTC download aggregates once production tracking is enabled;stats/summary.jsonis rebuilt only from these files.scripts/**: validation, generation, signing, and verification tooling.
Official plugin asset builds and release signing live in each plugin source
repository. A successful npm and GitHub release sends a plugin_release
repository dispatch. The registry verifies the GitHub checksum, archive,
embedded release signature, source coordinates, signed file list, and runtime
descriptor plus source-owned metadata before an idempotent automation branch
and pull request are created. A plugin_metadata dispatch accepts repository,
package, plugin, and source-commit coordinates and refreshes documentation
without changing any catalog release version or bundle.
Existing catalog versions use immutable assets from the public
lapis-notes/releases GitHub repository. New package-scoped plugin releases are
published from lapismd/lapis-plugins and indexed through the verified GitHub
dispatch workflow.
New plugin sources own a validated V2 registry.json beside their package
manifest. It supplies categories, plain-text highlights, documentation links,
source-owned image paths and optional structured-note overrides. The registry
fetches metadata, CHANGELOG.md and assets at the exact source commit, verifies
ownership, and mirrors hashed image variants under v2/assets/<plugin-id>/.
Historical V1 Markdown references remain in the archive.
Links use HTTPS and asset paths stay within the package. Media has bounded byte sizes and validated dimensions; gallery paths retain strict Storybook capture contracts. Badges and verified-owner claims stay curator-owned. Platform labels are preserved in metadata; runtime compatibility still checks supported hosts.
Cloudflare Pages CORS headers cover both registry versions and statistics.
Only anonymous /download/* archive delivery uses a Pages Function; catalog pages and
assets stay static. See download analytics for
metric, privacy, mirroring and recovery details. The Function streams only generated
release targets with CORS; clients retain signed archive verification and
transport-only fallback to the same artifact origin.
The production workflow requires the protected registry-production
environment and the V2 cutover variable. It verifies committed signatures and
production assets before deployment. Visual baseline updates remain separately
approved.
Source packages marked private: true are parked and excluded from the local
registry, including curated entries. Community is parked in the first-party
source repository for this release; Slides remains available for preview.