# プラグインを掲載する

プラグインのソースは、作者自身の公開 GitHub リポジトリに置いたままにします。プラグインを掲載または更新するには、作者が `EstrellaXD/Auto_Bangumi`（ベースブランチ `main`）に PR を作ります。PR では 1 つのファイル `plugins/registry/<id>.toml` を追加または編集します。

CI はこのファイルが指すコードを検査します。メンテナーがコードを読んでマージします。マージ後、CI がプラグインをパックして署名し、署名付きカタログに公開します。

::: tip バージョン要件
AutoBangumi 4.0.0-beta.2 以降はプラグイン用の鍵を信頼します。4.0.0-beta.1 は新しいカタログからプラグインをインストールできません。
:::

## 登録ファイル

ファイル `plugins/registry/<id>.toml` のフィールドは 4 つです。

```toml
repo = "owner/name"   # 公開 GitHub リポジトリ
commit = "<40 文字の完全な SHA>"   # タグは動かせるが、SHA は動かせない
path = "."   # 任意。プラグインのサブディレクトリ。既定はリポジトリのルート
sha256 = "<64 桁>"   # PR チェックで作られる zip の sha256。最初は省略し、CI が示す値を書きます
```

- ファイル名は `plugin.toml` の `id` と一致させます。
- `commit` は 40 文字の完全な SHA にします。短い SHA やタグは拒否されます。
- 名前、バージョン、`sdk` の範囲、作者、権限は、その commit の `plugin.toml` から読み取ります。登録ファイルに重複して書かないでください。
- `sha256` は署名をレビュー済みのバイトに結び付けます。マージ後に作り直した zip がこれと完全に一致するときだけ、CI は署名します。最初の push では省略できます。CI がサマリーに値を示すので、追記して再度 push します。

1 つの PR で複数のエントリを変更できます。1 PR に 1 プラグインを推奨します。

## 手順

1. リポジトリを準備します。リポジトリは公開にします。`plugin.toml`、プラグインのコード、`tests/` をコミットします。フロントエンドがある場合は、ソースを `web-src/` に置き、`package.json` と `pnpm-lock.yaml` もコミットします。
2. ローカルで確認します。

   ```bash
   ab-plugin validate .
   uv run pytest
   pnpm install --frozen-lockfile && pnpm build   # フロントエンドがある場合のみ
   ```

   `tests/` には少なくとも 1 つのテストが必要で、すべて合格しなければなりません。`ab-plugin new` が生成する契約テストはこの条件を満たします。
3. コードを公開リポジトリに push します。
4. 完全な SHA を取得します。

   ```bash
   git rev-parse HEAD
   ```

5. `EstrellaXD/Auto_Bangumi` を fork し、`plugins/registry/<id>.toml` を追加して、`main` に PR を作ります。変更するのは `plugins/registry/` 以下のファイルだけです。PR の説明ではプラグイン用テンプレート（`?template=plugin.md`）を使い、各項目にチェックを入れます。

## CI のルール

ワークフロー `plugin-registry.yml` のジョブ `check` が PR 上で実行されます。権限は読み取り専用で、secret はありません。変更された各エントリについて、まず固定された commit を取得します。次に下のルールを検査します。1 つでも満たさないと、CI はそのエントリを拒否します。

- `commit` が 40 文字の完全な SHA ではない。
- ファイル名がマニフェストの `id` と異なる。
- `id` が組み込みプラグインと衝突する、または予約 id である。
- `ab-plugin validate` が失敗する。
- 更新で、バージョンがカタログにあるバージョンより高くない。
- 更新で、`repo` が変更されている。プラグインを移管するには、下の「プラグインを移管する」を参照してください。
- `tests/` にテストがない、またはテストが失敗する。
- プラグインにフロントエンドがあるのに、`web-src/` がない。フロントエンドは、ソースを `web-src/` にコミットし、`package.json` と `pnpm-lock.yaml` を付けます。CI は pnpm 9 / Node 20 で `pnpm install --frozen-lockfile --ignore-scripts && pnpm build` を実行します。`@autobangumi/plugin-ui` はこのリポジトリのパッケージに解決します。コミット済みの `web/` は破棄します。

検査に通ると、CI は `ab-plugin pack` でパックし、次の内容を Job Summary に書き込みます。

- バージョンの変化。
- 比較リンク（更新）またはツリーリンク（新規）。
- validate とテストの結果。
- 拡張ポイント。
- 宣言された権限。
- フロントエンドの有無。
- zip の sha256。

## マージ後

メンテナー（CODEOWNERS：@EstrellaXD）が比較リンクでコードを読み、マージします。

マージ後、CI はカタログを増分で再構築します。`commit` が変わっていないエントリは、既存の zip を再利用します。次に、専用のプラグイン署名鍵で `catalog.json` とすべての zip に署名します。この鍵は更新用の鍵ではありません。最後に、CI がファイルを GitHub release `plugins` にアップロードします。

ユーザーは `GET /api/v1/plugins/catalog` で新しいプラグインやバージョンを確認できます。カタログの形式と署名は [署名と配布](/ja/dev/plugins/signing) を参照してください。

## プラグインを更新する

1. 自分のリポジトリでコードを変更し、`plugin.toml` の `version` を上げます。
2. push して、`git rev-parse HEAD` で新しい完全な SHA を取得します。
3. `main` に PR を作ります。`plugins/registry/<id>.toml` の `commit` を新しい SHA に変更し、CI サマリーの値で `sha256` を更新します。

バージョンはカタログにあるバージョンより高くする必要があります。そうでない場合、CI は PR を拒否します。

## プラグインを移管する

更新では `repo` を変更できません。プラグインを別のリポジトリに移すには、2 つの PR を使います。

1. 1 つ目の PR で `plugins/registry/<id>.toml` を削除します。
2. マージ後、2 つ目の PR で新しい `repo` を指定して、このファイルを再び追加します。このとき CI は新規プラグインとして検査するため、古いバージョンの制限は受けません。

## プラグインを削除する

`plugins/registry/<id>.toml` を削除する PR を作ります。マージ後、そのプラグインはカタログから外れます。ユーザーが既にインストールしたコピーは削除されません。

## 依存関係と再配布

- プラグインが依存できるのは、標準ライブラリと AutoBangumi に既にあるパッケージだけです。サードパーティの純 Python ライブラリは `vendor/` に入れてください。
- ライセンスは必須ではありません。ただし、PR を作ることで、作者は AutoBangumi がパック済みのプラグインを release で再配布することに同意したものとみなされます。