ReadAware

プラグインの公開

マーケットプレイスのパッケージは公開の readaware-pluginsリポジトリに置かれ、レビューを経て登録されます。現在のカタログはファーストパーティのみですが、この手順は外部からの提出を受け付ける場合にも契約となります。

レビュー可能なパッケージを準備する

TypeScriptの使用を推奨します。レビュー担当者がソースと成果物を比較できるよう、src/をビルド済みで自己完結したmain.jsの隣に置きます。ランタイムで使うアセットはすべてコミットしてください。リモートコードを読み込んだり、生成された巨大データに動作を隠したり、パッケージ外のファイルに依存したりしないでください。

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

リポジトリのチェックを実行する

bash
bun run build
bun run typecheck
bun test
bun run validate

検証では、レジストリとマニフェストの整合性、ID、バージョン、ケイパビリティ要件、権限、宣言されたファイル、パッケージ構成を確認します。これらのチェックは必要ですが十分ではありません。提出前にReadAwareデスクトップでビルド済みフォルダーを実際に動かしてください。

提出する

  1. 公開リポジトリをフォークします。
  2. テンプレートをplugins/<plugin-id>/へコピーし、フォルダー名をマニフェストIDと一致させます。
  3. パッケージと、必要なランタイムアセットをすべて追加します。
  4. ID順に並べた対応するエントリをregistry.jsonへ追加します。
  5. ルートの4つのチェックをすべて実行し、ビルド済みフォルダーからのローカルインストールをテストします。
  6. 動作、プライベートデータ、外部サービス、各権限と設定許可の理由を説明するプルリクエストを作成します。

レビューチェックリスト

  • 機能が既存のドメイン、コントリビューション、サービスのうち、最も狭い範囲のケイパビリティを使っている。
  • requiresに使用するすべての契約が、妥当なsemver範囲とともに記載されている。
  • 権限とsettingsAccessが実際のランタイム呼び出しと一致し、推測に基づく権限を含んでいない。
  • activate()は動作を登録するだけで、業務上または外部への副作用を実行しない。
  • プラグイン専用データに安定したスキーマがあり、すべてのバージョン移行にテスト済みのマイグレーションがある。
  • ネットワークエンドポイント、LLMの利用、認証情報、スケジュール、データ保持について、ユーザー向けの言葉で説明されている。
  • ホスト描画ビューが、キーボードナビゲーション、長いテキスト、空データ、ライトテーマとダークテーマに対応している。
  • ソースが読みやすく、生成物を再現でき、アナリティクス、トラッキング、難読化、リモートコードの読み込みが存在しない。

権限プレビューは提出前の確認に役立ちます。正式なチェックは、リポジトリの検証と人によるレビューです。

更新とデータマイグレーション

manifest.jsonとregistry.jsonの両方でパッケージバージョンを上げます。schemaVersionを上げるのは、プライベートKVまたはドキュメントの構造が変わる場合だけにし、対応するmigrate()を同じ候補に含めます。

現実的なデータを使って、更新と意図的なダウングレードをテストします。ReadAwareは候補をステージングしてヘルスチェックを行い、プラグインのファイルとデータをスナップショットし、マイグレーション中は旧ランタイムを静止させ、成功した後にだけ昇格させます。更新に失敗しても、以前のパッケージとデータを引き続き使用できなければなりません。

権限の変更

新しい権限は、マニフェストの整理ではなくプロダクトの変更として扱います。以前の権限セットでは不十分な理由、アクセス可能になるユーザーデータまたは外部操作、ユーザーが拒否した場合の結果を説明します。コードが使わなくなった権限は削除してください。

現在の配布における信頼性

Workerの分離とケイパビリティの強制により過剰な権限行使は抑えられますが、インストールが信頼に基づく判断であることは変わりません。広く第三者に開かれたマーケットプレイスにする前に、ReadAwareには発行者の身元確認、決定論的なパッケージング、署名と完全性の検証、レビューの出所情報、失効、権限差分のレビュー、セキュリティ対応経路が必要です。

これらの仕組みが提供されるまでは、リポジトリにマージされたエントリはレビューの証拠であって、任意の悪意あるコードが安全だという数学的保証ではありません。

プルリクエストを作成する前に

プラグインをビルドするを読み直し、最終マニフェストをケイパビリティツールで比較し、古いshelfやappearanceの例ではなく、現在のAPI契約にパッケージが従っていることを確認します。