Render mutable registry README details #197

New issue

Closed

opened 2026-06-01 14:09:33 +00:00 by steve · 0 comments

steve commented

2026-06-01 14:09:33 +00:00

Owner

Problem

Plugin registry detail views only expose the short registry description, while
users expect richer Obsidian/VS Code-style detail pages. Rich descriptions
should be mutable documentation links so README copy can change without
repackaging plugin release assets or republishing registry metadata.

Goal

Add a signed mutable readmeUrl metadata field to official plugin registry
metadata and render that README markdown in the Lapis plugin detail UI when
available.

Scope

Extend registry metadata contracts consumed by the app with optional
readmeUrl.
Render fetched README markdown in the app plugin detail surface with
sanitization, loading, failure, missing-URL fallback states, and session cache.
Keep the short description as the listing summary.
Update app spec coverage for mutable README detail behavior.
Coordinate with the registry repo implementation that validates, preserves,
generates, signs, and optionally renders readmeUrl.

Non-goals

Adding screenshots/media fields in this phase.
Treating README markdown as installable or trusted runtime code.
Requiring a registry republish when content at an unchanged README URL changes.
Moving Bases into the installable registry.

Acceptance Criteria

Registry metadata types include optional readmeUrl and reject non-HTTPS URLs
in the registry repo.
The app plugin detail UI fetches and renders readmeUrl markdown when present.
README rendering is sanitized before insertion into the DOM.
README fetches have loading, failure, and missing-URL fallback states.
README content is cached per URL for the current browser session.
Existing plugin install/enable/status actions remain independent of README
loading failures.
Workspace/API checks and relevant script tests pass before closure.

Implementation Notes

Use Forgejo raw README URLs as the preferred official source.
Registry sync must preserve manually curated readmeUrl values.
App rendering should tolerate older registry metadata without readmeUrl.

Suggested Files or Specs To Inspect

spec/src/30-cross-package-contracts/plugin-registry.md
Registry settings/plugin manager UI under packages/workspace/src
Plugin registry client and metadata types under packages/api/src
/Users/stevejuma/code/lapis-plugin-registry/schemas
/Users/stevejuma/code/lapis-plugin-registry/src/pages/plugins/[id].astro

Validation Commands

pnpm --filter @lapis-notes/api check:all
pnpm --filter @lapis-notes/workspace check:all
pnpm check:all
make spec-lint
mdbook build spec
Registry repo: pnpm registry:validate
Registry repo: pnpm check

Follow-up to #185 — Migrate remaining installable first-party plugins to the official registry

Follow-up Tasks

Implementation Summary

Added mutable registry readmeUrl metadata support, app-side README fetching/rendering, package READMEs for external official plugins, and updated registry trust fixtures.

## Problem Plugin registry detail views only expose the short registry description, while users expect richer Obsidian/VS Code-style detail pages. Rich descriptions should be mutable documentation links so README copy can change without repackaging plugin release assets or republishing registry metadata. ## Goal Add a signed mutable `readmeUrl` metadata field to official plugin registry metadata and render that README markdown in the Lapis plugin detail UI when available. ## Scope - Extend registry metadata contracts consumed by the app with optional `readmeUrl`. - Render fetched README markdown in the app plugin detail surface with sanitization, loading, failure, missing-URL fallback states, and session cache. - Keep the short `description` as the listing summary. - Update app spec coverage for mutable README detail behavior. - Coordinate with the registry repo implementation that validates, preserves, generates, signs, and optionally renders `readmeUrl`. ## Non-goals - Adding screenshots/media fields in this phase. - Treating README markdown as installable or trusted runtime code. - Requiring a registry republish when content at an unchanged README URL changes. - Moving Bases into the installable registry. ## Acceptance Criteria - Registry metadata types include optional `readmeUrl` and reject non-HTTPS URLs in the registry repo. - The app plugin detail UI fetches and renders `readmeUrl` markdown when present. - README rendering is sanitized before insertion into the DOM. - README fetches have loading, failure, and missing-URL fallback states. - README content is cached per URL for the current browser session. - Existing plugin install/enable/status actions remain independent of README loading failures. - Workspace/API checks and relevant script tests pass before closure. ## Implementation Notes - Use Forgejo raw README URLs as the preferred official source. - Registry sync must preserve manually curated `readmeUrl` values. - App rendering should tolerate older registry metadata without `readmeUrl`. ## Suggested Files or Specs To Inspect - `spec/src/30-cross-package-contracts/plugin-registry.md` - Registry settings/plugin manager UI under `packages/workspace/src` - Plugin registry client and metadata types under `packages/api/src` - `/Users/stevejuma/code/lapis-plugin-registry/schemas` - `/Users/stevejuma/code/lapis-plugin-registry/src/pages/plugins/[id].astro` ## Validation Commands - `pnpm --filter @lapis-notes/api check:all` - `pnpm --filter @lapis-notes/workspace check:all` - `pnpm check:all` - `make spec-lint` - `mdbook build spec` - Registry repo: `pnpm registry:validate` - Registry repo: `pnpm check` ## Related Issues - Follow-up to #185 — [Migrate remaining installable first-party plugins to the official registry](../open/185-migrate-remaining-installable-first-party-plugins-to-the-official-registry.md) ## Follow-up Tasks ## Implementation Summary Added mutable registry readmeUrl metadata support, app-side README fetching/rendering, package READMEs for external official plugins, and updated registry trust fixtures.

steve added this to the Full Registry V1 milestone

2026-06-01 14:09:33 +00:00

steve

2026-06-01 14:09:33 +00:00