[registry] Validate module formats and shared dependencies #221

New issue

Closed

opened 2026-06-02 09:43:39 +00:00 by steve · 0 comments

steve commented

2026-06-02 09:43:39 +00:00

Owner

Problem

Official registry publication and installation need to reject loader-incompatible module metadata before incompatible plugins reach users.

Goal

Extend registry validation to enforce module formats, entry files, shared dependencies, and platform compatibility using the generated host-module catalogue.

Scope

Extend registry release metadata and schemas with formats and runtime metadata.
Validate ESM, CommonJS fallback, and sidecar entry files exist.
Validate shared dependencies against the generated host catalogue per platform.
Reject undeclared externals in official plugin bundles.
Reject renderer plugins that declare desktop-only dependencies and sidecar plugins that import renderer-only modules.
Allow community/manual compatibility paths to continue with warnings where appropriate.

Non-goals

Do not introduce a second hand-maintained dependency allowlist.
Do not block manual community plugins from Obsidian-compatible CommonJS loading solely because official metadata is absent.
Do not implement plugin build changes in this issue.

Acceptance Criteria

Invalid official ESM/shared-dependency metadata is rejected by registry validation.
Install/enable compatibility warnings are available to the app.
Registry rules use generated catalogue metadata, not a second hand-maintained list.

Implementation Notes

Distinguish official provenance from plugin-controlled manifest content.
Keep sidecar shared dependency rules narrower than renderer dependency rules.
Prefer warnings for manual/community paths and hard failures for official publication/install validation.
Add signed release runtime metadata by mirroring structured lapis.runtime.entries and shared dependency defaults into the official release manifest generated by scripts/plugin-release.mjs.
Add an API distribution validator that runs after signed release files have been downloaded and verified. It should compare the signed runtime metadata with the packaged manifest.json, validate entry and fallback files, check declared and scanned bare dependencies against plugin-host-modules.schema.generated.ts, and return structured diagnostics.
Wire the validator into VerifiedPluginInstaller so official invalid runtime metadata fails before staging files, while non-official/manual compatibility paths can surface warnings.
Record warning diagnostics on installed plugin provenance records so the app can surface install/enable compatibility warnings without treating them as proof of official status.
Update registry/runtime specs to document the signed runtime metadata and official validation rules.

Suggested Files or Specs To Inspect

spec/src/50-roadmap/full-registry-v1.md
spec/src/30-cross-package-contracts/plugin-registry.md
packages/api/src/lib/plugin-distribution/
packages/api/src/lib/generated/plugin-host-modules.schema.generated.ts

Validation Commands

pnpm plugin-host:check
pnpm --filter @lapis-notes/api check:all
pnpm check:all

Follow-up Tasks

Implementation Summary

Added signed release runtime metadata, official runtime-entry and shared-dependency validation against the generated host-module catalogue, installer hard failures for invalid official metadata, runtime warning persistence for compatibility paths, release-tool metadata emission, focused tests, and spec updates.

## Problem Official registry publication and installation need to reject loader-incompatible module metadata before incompatible plugins reach users. ## Goal Extend registry validation to enforce module formats, entry files, shared dependencies, and platform compatibility using the generated host-module catalogue. ## Scope - Extend registry release metadata and schemas with formats and runtime metadata. - Validate ESM, CommonJS fallback, and sidecar entry files exist. - Validate shared dependencies against the generated host catalogue per platform. - Reject undeclared externals in official plugin bundles. - Reject renderer plugins that declare desktop-only dependencies and sidecar plugins that import renderer-only modules. - Allow community/manual compatibility paths to continue with warnings where appropriate. ## Non-goals - Do not introduce a second hand-maintained dependency allowlist. - Do not block manual community plugins from Obsidian-compatible CommonJS loading solely because official metadata is absent. - Do not implement plugin build changes in this issue. ## Acceptance Criteria - Invalid official ESM/shared-dependency metadata is rejected by registry validation. - Install/enable compatibility warnings are available to the app. - Registry rules use generated catalogue metadata, not a second hand-maintained list. ## Implementation Notes - Distinguish official provenance from plugin-controlled manifest content. - Keep sidecar shared dependency rules narrower than renderer dependency rules. - Prefer warnings for manual/community paths and hard failures for official publication/install validation. - Add signed release runtime metadata by mirroring structured `lapis.runtime.entries` and shared dependency defaults into the official release manifest generated by `scripts/plugin-release.mjs`. - Add an API distribution validator that runs after signed release files have been downloaded and verified. It should compare the signed runtime metadata with the packaged `manifest.json`, validate entry and fallback files, check declared and scanned bare dependencies against `plugin-host-modules.schema.generated.ts`, and return structured diagnostics. - Wire the validator into `VerifiedPluginInstaller` so official invalid runtime metadata fails before staging files, while non-official/manual compatibility paths can surface warnings. - Record warning diagnostics on installed plugin provenance records so the app can surface install/enable compatibility warnings without treating them as proof of official status. - Update registry/runtime specs to document the signed runtime metadata and official validation rules. ## Suggested Files or Specs To Inspect - `spec/src/50-roadmap/full-registry-v1.md` - `spec/src/30-cross-package-contracts/plugin-registry.md` - `packages/api/src/lib/plugin-distribution/` - `packages/api/src/lib/generated/plugin-host-modules.schema.generated.ts` ## Validation Commands - `pnpm plugin-host:check` - `pnpm --filter @lapis-notes/api check:all` - `pnpm check:all` ## Related Issues ## Follow-up Tasks ## Implementation Summary Added signed release runtime metadata, official runtime-entry and shared-dependency validation against the generated host-module catalogue, installer hard failures for invalid official metadata, runtime warning persistence for compatibility paths, release-tool metadata emission, focused tests, and spec updates.

steve added this to the Dual ESM/CJS plugin loader milestone

2026-06-02 09:43:39 +00:00

steve

2026-06-02 09:43:39 +00:00