Publishing a plugin

Marketplace packages live in the public readaware-plugins repository and enter through review. The current catalog is first-party; this process is also the contract for opening it to external submissions.

Prepare a reviewable package

TypeScript is recommended. Keep src/ beside the built, self-contained main.js so reviewers can compare source and artifact. Commit every runtime asset. Do not load remote code, hide behavior in generated blobs, or depend on files outside the package.

plugins/my-plugin/
  manifest.json
  main.js
  package.json
  tsconfig.json
  src/main.ts
  assets/…

Run the repository checks

bun run build
bun run typecheck
bun test
bun run validate

Validation checks registry-to-manifest consistency, IDs, versions, capability requirements, permissions, declared files, and package shape. These checks are necessary, not sufficient: exercise the built folder in ReadAware desktop before submitting it.

Submit

1. Fork the public repository.
2. Copy the template into plugins/<plugin-id>/ and keep the folder name equal to the manifest ID.
3. Add the package and every required runtime asset.
4. Add the matching, ID-sorted entry to registry.json.
5. Run all four root checks and test local installation from the built folder.
6. Open a pull request describing behavior, private data, external services, and the reason for every permission and Settings grant.

Review checklist

• The feature uses the narrowest existing Domain, Contribution, and Service capabilities.
• requires names every used contract with a defensible semver range.
• Permissions and settingsAccess match actual runtime calls and contain no speculative authority.
• activate() registers behavior but performs no business or external side effects.
• Plugin-private data has a stable schema and every version transition has a tested migration.
• Network endpoints, LLM use, credentials, schedules, and data retention are explained in user-facing language.
• Host-rendered views work with keyboard navigation, long text, empty data, and light and dark themes.
• Source is readable; generated output is reproducible; no analytics, tracking, obfuscation, or remote code loading is present.

The permission preview is a useful preflight. Repository validation and human review remain the authoritative checks.

Updates and data migration

Bump the package version in both manifest.json and registry.json. Bump schemaVersion only when private KV or document shape changes, and ship the corresponding migrate() in the same candidate.

Test update and deliberate downgrade against realistic data. ReadAware stages and health-checks the candidate, snapshots plugin files and data, quiesces the old runtime for migration, and promotes only after success. A failed update must leave the previous package and data usable.

Permission changes

Treat new authority as a product change, not manifest housekeeping. Explain why the previous permission set is insufficient, which user data or external operation becomes reachable, and what happens when the user declines. Remove permissions that the code no longer uses.

Distribution trust today

Worker isolation and capability enforcement reduce overreach, but installation is still a trust decision. Before a broad third-party marketplace, ReadAware still needs publisher identity, deterministic packaging, signing and integrity verification, review provenance, revocation, permission-diff review, and a security response path.

Until those controls ship, a merged repository entry is review evidence, not a mathematical guarantee that arbitrary hostile code is safe.

Before opening the pull request

Re-read Build a plugin, compare the final manifest in the capability tools, and confirm the package follows the current API contract rather than an oldershelf or appearance example.