プラグイン開発
tessoa プラグイン は、サンドボックスの中で動作する小さなプログラムで、TypeScript または Rust で作成します。プラグインは、右クリックメニューへのコマンドの追加、ページ全体の内容の提供、ファイル一覧への列の追加、設定（Settings） への独自オプションの追加を行えます。このページでは、公式テンプレートを使ってプラグインを開発、テスト、パッケージ化する手順を説明します。始める前に、コマンドラインと Git を使える環境を用意してください。
このページのプラグインプラットフォームには tessoa 0.29.0 以降が必要です。プロジェクトの作成、テスト、パッケージ化に tessoa のインストールは必要ありません。tessoa に組み込んで試すには、バージョン 0.29.0 以降が必要です。動画や Office 文書などのプレビューを担う プレビュープラグイン とは別の仕組みです。プレビュープラグインは tessoa が公式に提供しています。
プラグインの機能
プラグインは次の表の機能を 1 つ以上提供します。各機能はプラグインのマニフェストファイル plugin.toml で宣言します。
| 機能 | 説明 |
|---|---|
| コマンド | 右クリックメニューに表示され、選択したファイルに対して動作します。例：写真を撮影日で名前変更する |
| ページ | タブ全体、またはサイドバーの 1 セクションです。電卓やタスクボードなどが該当します。内容はプラグインが記述し、tessoa が自身のスタイルで描画します |
| 列 | ファイル一覧に追加する列です。ユーザーは 列メニュー から表示できます |
| 設定 | プラグイン独自のオプションです。tessoa の設定に表示され、tessoa が保存します |
| タスク | 時間のかかる処理をバックグラウンドで実行します。進行状況を表示し、キャンセルできます |
サンドボックスと権限
プラグインは独立したプロセスの WebAssembly サンドボックスで動作します。ファイルパスを見ることはできず、ディスクの読み書き、ネットワーク接続、プログラムの起動も単独では行えません。ユーザーが選択したファイルはハンドルとしてプラグインに渡され、ファイルを変更する場合は tessoa に処理を依頼します。こうした変更は元に戻すことができ、アクティビティ（Activity） に記録されます。
プラグインにできることは 3 つのレベルに分かれます。
| レベル | 付与のされ方 | 含まれるもの |
|---|---|---|
| 自動 | 宣言は不要です | ログ、通知、ダイアログ、選択したファイルの名前やサイズなどの情報、プラグイン専用のストレージ、ページ、設定、タスク |
| 宣言 | plugin.toml の [permissions] に記載し、インストール時にユーザーへ表示されます | プラグインに渡されたファイルの読み取り、選択したファイルの名前変更、クリップボードへの書き込み、マニフェストに記載した Web サイトへの接続など |
| ユーザーの同意 | 宣言したうえで、ユーザーが tessoa 内で確認します | 今後のバージョン向けに予約されています：フォルダー全体の読み取り、既存ファイルの内容の変更 |
プラグインが実際に使う権限だけを宣言してください。権限名の一覧は、テンプレート内の sdk/docs/guide/permissions.md にあります。
開発環境の準備
- tessoa-plugin-template を開き、Use this template をクリックして自分のリポジトリを作成し、ローカルにクローンします。
- リポジトリ内でセットアップスクリプトを実行します。スクリプトは不足しているツールだけをインストールします。TypeScript には Node.js、Rust には Rust が必要で、どちらの場合もコマンドラインツール
tessoa-pluginが必要です。
| システム | コマンド |
|---|---|
| Windows | powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -Lang ts |
| macOS、Linux | bash scripts/setup.sh --lang ts |
Rust で作成する場合は、ts を rust に置き換えます。スクリプトは現在のユーザーにだけインストールし、管理者権限は必要ありません。
プラグインプロジェクトの作成
tessoa-plugin init --lang ts --id com.example.my-plugin --name "My plugin"を実行します。選んだ言語のスケルトンがリポジトリのルートへ移動し、プラグインの ID と名前が設定され、もう一方の言語のスケルトンは削除されます。tessoa-plugin doctorを実行して、ツールがそろっているか確認します。FAIL と表示された項目を修正してから次へ進みます。
プラグイン ID は全体で一意で、ドメインを逆順にした形式で書きます。使える文字は英小文字、数字、.、_、- だけです。
プラグインの作成
プラグインは 2 つの部分から成ります。マニフェスト plugin.toml はプラグインが提供するものと必要な権限を宣言し、src/ にコードを置きます。次のマニフェストは、選択した画像に対してだけ表示される右クリックメニューのコマンドを宣言しており、選択したファイルの読み取りと名前変更の権限を必要とします。
[plugin]
id = "com.example.rename-by-date"
name = "撮影日で名前変更"
version = "0.1.0"
api = "tessoa:plugin@0.2.0"
min-host = "0.29.0"
[entry]
kind = "wasm"
file = "dist/plugin.wasm"
[[commands]]
id = "rename-by-date"
title = "撮影日で名前変更"
where = ["context-menu"]
when = { ext = ["jpg", "jpeg", "heic", "png"], min-selected = 1 }
[permissions]
files = ["read-selected", "rename-selected"]テンプレートの examples/ には、それぞれテスト付きの完成したプラグインがいくつかあり、参考として利用できます。マニフェストの各項目は sdk/docs/guide/manifest.md で、API リファレンスは sdk/docs/api/ で説明しています。
テンプレートはコーディングアシスタントの作業方法に合わせて構成されています。リポジトリのルートにある AGENTS.md が、アシスタントを sdk/ 内のマニュアルへ案内します。リポジトリをコーディングアシスタントで開き、「選択した写真を撮影日で名前変更する右クリックコマンド」のように 1 文で説明すると、プロジェクトの作成、実装、テスト、パッケージ化まで進められます。
テストとパッケージ化
テストシナリオは tests/scenarios/*.toml に、テストで使うファイルは tests/fixtures/ に置きます。tessoa-plugin test は本物のサンドボックスで、模擬した tessoa を相手にプラグインを実行します。そのため、テストに tessoa のインストールは必要ありません。
| コマンド | 内容 |
|---|---|
tessoa-plugin test | プラグインをビルドし、すべてのテストシナリオを実行します |
tessoa-plugin run | 指定したファイルに対してコマンドを 1 つ実行します。ファイルは実際に変更されます |
tessoa-plugin check | マニフェストを確認し、ビルド結果が使うインターフェースを監査します |
tessoa-plugin package | dist/<id>-<version>.zip を作成します。監査に通らないプラグインはパッケージ化しません |
tessoa-plugin upgrade | コマンドラインツールと sdk/ を更新します。ダウンロード前に署名とチェックサムを確認します |
tessoa で試す
- tessoa 0.29.0 以降を起動します。
- プラグインプロジェクトで
tessoa-plugin installを実行します。プラグインをビルドして監査したあと、プロジェクトフォルダーを実行中の tessoa に渡します。 - 初回は、プラグインが求める権限が tessoa のウィンドウに一覧表示されます。確認するとプラグインが有効になります。以降はビルドのたびに tessoa がプラグインを自動で再読み込みします。
プラグインを tessoa に組み込むには有効なライセンスが必要です。プロジェクトの作成、テスト、パッケージ化には必要ありません。
プラグインの公開
プラグインコミュニティでプラグインを公開する機能は準備中です。それまでは、パッケージ化した ZIP とソースコードを自分の GitHub リポジトリで共有できます。テンプレートのスケルトンとサンプルは MIT ライセンスで公開されているため、それらを使って作ったプラグインは自由に使用、変更、公開、販売できます。sdk/ には別のライセンスがあり、sdk/LICENSE.md に記載されています。