プラグイン
ドキュメント作成中
一部の内容はまだ不完全な場合があります。
プラグインは、右サイドバーにパネルを 1 つ加える独立したプログラムです。ThinkTerm はそれを起動し、やり取りし、送られてきたものを描きます — デスクトップのウィンドウでもブラウザでも同じです — が、そのコードは ThinkTerm の中では一切動きません。プラグインがクラッシュしても、道連れになるのはそのパネルだけで、ほかには及びません。
ファイルとノート で説明したスニペットもプラグインです。内蔵されていて、インストールするプラグインと同じインターフェースを使っています。
プラグインが現れる場所
右サイドバーの中だけです。パネルを持つプラグインは、サイドバーの切り替えにファイル、ノート、スニペットと並んで自分の名前で現れ、設定 › サイドバーとプラグイン に一覧されます。独自のコマンド、メニュー項目、通知は加えず、コマンドパレットにも何も加えません。プラグインに関わるキーは、そのパネルにキーボードを渡すためのアクション 1 つだけで、割り当てられます — パネルでの入力 と キーボードとコマンド を参照してください。
サイドバーに収まりきらないほど見せるものがあるパネルは、その左にもっと広いビューを開けます。幅はドラッグした分だけです。その場所がないとき — 狭いウィンドウやスマートフォン — プラグインはそこに出すはずだったものをパネル自体に収めます。
パネルはブラウザでもデスクトップと同じに見えます。どちらも同じコードで、ThinkTerm 自身の色で描くからです。ブラウザが使うのは、ページを渡したサーバーがあるマシンのプラグインで、ブラウザが動いているデバイスのものではありません — そのためヘッドレスのホストはそのホスト自身のプラグインを見せ、サーバー用パッケージにもプラグインサーバーが同梱されています。ウェブアクセス を参照してください。
パネルでの入力
パネルには入力用のフィールドを置けます。1 行、複数行、あるいは点で伏せて表示する秘密のフィールドです。ThinkTerm が自身のフォントと色でそれを描き、編集も自分で行うので、入力メソッド、選択、クリップボードはウィンドウ内のほかの場所と同じように働きます。秘密のフィールドからはコピーも切り取りもできず、その中身はあなたが送信したときにだけプラグインに届きます。
キーボードは、あなたがパネルに渡すまで端末のものです。フィールドの中でクリックすればそこにキーボードが渡ります。パネルのそれ以外の場所をクリックしても渡らないので、クリックはただのクリックです。デスクトップでは、FocusPluginPanel でパネルにキーを割り当てることもできます。それは右サイドバーをそのパネルに切り替え、最初のフィールドにキーボードを置きます。もう一度押すと、キーボードは戻ります。
config.keys = {
{ key = 'S', mods = 'CMD|SHIFT', action = wezterm.action.FocusPluginPanel 'stocks' },
}ブラウザにはそのようなキーはありません。そこではパネルはフィールドを通じてキーボードを得ます。
パネルがキーボードを持っている間、プラグインに届くのは、それが求めた少数のキー（矢印など）と、フィールドの中身です。Ctrl、Alt、Command を押したキーは届きません。Escape か端末のクリックでキーボードは戻り、Tab でパネルのフィールドの間を移れます。あなたが取り上げたのではなくパネルがキーボードを失ったとき — たとえばプラグインが止まったとき — 次に打ったものは、Escape を押すかクリックするまでどこにも行かず、端末にも届きません。
インストールと削除
プラグインは、plugin.toml と実行するプログラムを収めたディレクトリです。インストールとは、そのディレクトリをプラグインディレクトリに置くことです。
| システム | プラグインディレクトリ |
|---|---|
| macOS | ~/Library/Application Support/ThinkTerm/plugins |
| Linux | ~/.local/share/ThinkTerm/plugins |
| Windows | %APPDATA%\ThinkTerm\plugins |
インストールの手順も再起動もありません。ThinkTerm は次に見に行ったときに新しいプラグインに気づきます。設定 › サイドバーとプラグイン を開いたとき、または thinkterm plugin list を実行したときです。ディレクトリを消せば削除になります。
初めて見るプラグインは new で、あなたが許可するまで何も実行されません。設定 › サイドバーとプラグイン では、デスクトップでもブラウザでも 許可 ボタン付きで 新しいプラグイン：許可するまで実行されません と表示されます。シェルからは thinkterm plugin enable <id> で許可でき、thinkterm plugin list はその状態を new と示します。許可するまで、そのパネルは出ず、呼び出しは拒否され、プログラムは起動されません — 常駐 にしていても同じです。
ThinkTerm は、あなたがプラグインを許可したディレクトリを覚えています。移動したとき、リンクが別のコピーを指したとき、別のプラグインがその id を使ったとき、マニフェストが別の id を付けたとき、プラグインはもう一度 new になり、動いていたコピーは止められます。プラグインをその場で更新したり、シンボリックリンク経由で開発中のものをビルドし直したりしても、再び尋ねられることはありません。プラグインディレクトリの隣にある plugins.json では、待っているプラグインはオフとして書かれるので、このファイルを共有する古い ThinkTerm もそれを実行しません。別の場所にあったためだけにオフになったものは、許可した場所に戻ればオンに戻ります。自分でオフにしたものはオフのままです。
プラグインを代わりにダウンロードしたりインストールしたりするものはなく、アプリの中に選べるカタログもありません。マシン上のプラグインはすべて、誰かがそこへコピーしたものです。プラグインを共有する人たちは、GitHub にトピック thinkterm-plugin を付けて置き、リポジトリのルートに plugin.toml を置いています。そうすればプラグインディレクトリにクローンするだけでインストールが済みます。プラグインはあなたとして動くプログラムです。どこから届いたものでも、信頼できるものだけをコピーしてください。
コマンドライン
thinkterm plugin は、シェルからプラグインを確認し、操作します。
| コマンド | 内容 |
|---|---|
thinkterm plugin list | すべてのプラグインと、その状態（許可待ちなら new）とバージョン |
thinkterm plugin enable <id> | プラグインをオンにする。new のものは、同時に実行も許可する |
thinkterm plugin disable <id> | プラグインをオフにする |
thinkterm plugin reload [<id>] | プラグインを止めてマニフェストを読み直す。id を省くとインストール済みのすべてが対象 |
thinkterm plugin call <id> <json> | プラグインに呼び出しを送り、その答えを出力する |
thinkterm plugin dir | プラグインディレクトリを出力する |
reload は、クラッシュや失敗の状態も解除し、もう一度試せるようにします。同じスイッチ、再読み込み ボタン、プラグインフォルダーを開く手段は 設定 › サイドバーとプラグイン にもあります。
プラグインの動き方
プラグインを動かすのはウィンドウではありません。GUI ともセッションサーバーとも別の小さなプロセス thinkterm-plugin-server の下で動き、デスクトップ、ブラウザ、コマンドラインはどれもこれとやり取りします。マシンごと、ユーザーごとに 1 つです。何かが初めてプラグインを必要としたときに起動し、最後の利用者がいなくなってから 30 秒で終了し、そのときすべてのプラグインを止めます。
許可したインストール済みのプラグインは、それぞれがさらに独立したプロセスで、初めて使われたとき — パネルが表示されたとき、またはコマンドラインから呼び出されたとき — に起動します。予期せず終了したプラグインは停止したと表示され、次に使われたときに起動し直します。1 分間に 3 回クラッシュしたものは失敗とされ、再読み込みするか、そのファイルが変わるまで放っておかれます。プログラムがディスク上で変わると、ThinkTerm は次に使う前にそれを再起動します。
使われていないプラグインがどれだけ動くか
プラグインは、そのパネルのどれかがどこか — ウィンドウでもブラウザでも — に表示されている間、あるいはそれへの呼び出しが答えを待っている間、使用中です。使用中でなくなった後、プログラムがどれだけ動き続けるかはバックグラウンドの設定で決まります。
| 設定 | 起動 | 停止 |
|---|---|---|
常駐 | そのマシンの ThinkTerm と一緒に | そのマシンの ThinkTerm がいなくなったとき |
必要なときだけ（既定） | 使われたとき | 最後に使われてから 2 分後 |
使ったら停止 | 使われたとき | 最後に使われてから 10 秒後 |
どれが要るかはプラグインのマニフェストが示します。設定 › サイドバーとプラグイン で各プラグインの横にあるメニューは、デスクトップでもブラウザでも、プラグインごとにそれを上書きします。メニューでは、マニフェストが求めたものに プラグインの既定 と記されます。
ここでの兼ね合いは、パネルを開いた瞬間に準備ができていることと、見ていない間はプログラムが動いていないことの間にあります。常駐 は何かを見張っておくプラグインに向いていて、ThinkTerm が頼まれずにプラグインを起動するのはこのモードだけで、それも許可したプラグインに限ります。常駐のプラグインが自分で止まると、失敗とされるまで 2 秒後に起動し直されます。
「そのマシンの ThinkTerm」とは、デスクトップアプリかセッションサーバーのうち、動いているほうです。デスクトップのないホストではセッションサーバーなので、そこで常駐にしたプラグインはそのサーバーと同じだけ動きます。選択はマシンごとに保たれます。同じプラグインを、サーバーでは常駐に、ノート PC では必要なときだけにできます。
パネルの隣の端末
プラグインには、パネルの隣の端末に thinkterm cli でどう届くかが伝えられ、プラグインのプログラムは THINKTERM_CLI に、ThinkTerm が同梱している thinkterm を見つけます。これらを使えば、プラグインはその端末が表示している内容を読み、各ペインで何が動いているかを一覧にし、そこで起きること — プログラムやコマンドの終了、タイトル、状態レポート — を、コマンドラインに書かれたコマンドで追えます。別のマシンの端末へは、それを表示している ThinkTerm を通して届き、頼んだことが引き渡されます。端末はフォーカスのあるペインで、そちらへ移るとすぐに、プラグインに新しい端末が伝えられます。そのディレクトリと、別のマシンかどうかは、そのペインが自分の居場所を伝えたあとに追いつきます。
別のマシンの端末
パネルは隣の端末 — そのウィンドウでフォーカスのあるペイン — に属し、プラグインにはその端末のディレクトリが伝えられます。その端末が SSH でつないだ別のマシンで動いているとき、プラグイン自体はこちら、このマシンで動いたままです。向こうでしたいことは ThinkTerm に頼みます。プログラムを実行する、ファイルを読む、あるパスに何があるかを調べる、のいずれかです。ThinkTerm はそれを、ファイルパネルが使うのと同じ接続で、あなたとして行います。
こうした依頼には、知っておくべき制限があります。
- 届くのはプラグインのパネルの隣にある端末のマシンだけで、その端末がまだそこにある間だけです。端末がすでに離れたマシンへの依頼は失敗します。
- ThinkTerm がマシンに接続するのは、あなたが許してからです。ファイルパネルで、あるいはパネルが中身の代わりに表示するボタンで許します。それまでは、どの依頼も失敗します。ファイルパネルで許せば、プラグインにも通用します。ホストで
ファイルパネルを自動で接続がオンなら、そのホストの端末の隣でファイルパネルが表示されたときに自動で許可されます。プラグインのパネルが表示されているだけでは、そうはなりません。 - 向こうで実行したプログラムは 20 秒で止められます。
これはデスクトップの機能です。ブラウザのパネルは、この方法でほかのマシンに届きません。
プラグインにできること
プラグインはあなたがマシンに置いたプログラムで、あなたとして、あなたの権限で動きます。許可するまで何も実行されないので、あなたの知らないうちにプラグインディレクトリに現れたプラグインは、一覧に載るだけです。許可したあとも、ThinkTerm はサイドバーの外にプラグインのものを何も表示しませんが、それでプログラム自身がファイルを読んだり、ネットワークを使ったり、ほかのプログラムを実行したりするのを止められるわけではありません。止められるのはサンドボックスだけで、それはありません。ほかのプログラムをインストールするのと同じつもりでインストールしてください。
リモートへの依頼は、これを SSH でつないだマシンにまで広げます。ここで信頼するプラグインは、そのパネルの隣に端末があるすべてのホストで信頼するプラグインでもあります。上の制限が狭めるのは、それらにいつ届くかであって、届いた後に何ができるかではありません。同じように、プラグインはパネルの隣の端末が表示するものをすべて読めます。あなたとして thinkterm cli を実行できる人なら誰でもそうであるのと同じです。
ThinkTerm のソースにあるプラグイン
ThinkTerm のソースには plugins/ の下に 3 つのプラグインがあります。ダウンロードには含まれていません。どれも Cargo でビルドし、その plugin.toml とプログラムをプラグインディレクトリの中の専用のディレクトリにコピーしてインストールします。
- Diff（
diff）は、隣の端末がいる git リポジトリの、最後のコミット以降の変更を GitHub Desktop のように表示します。変更されたファイルはパネルに、選んだファイルの各行は広いビューに出て、変わった行には印が付きます。ファイルの上のフィールドは、パスにそのテキストを含むファイルだけに（大文字小文字を問わず）絞り込みます。パネルにキーボードがあるとき、上下キーで前後のファイルを選び、フィールドで Return を押すと残った最初のファイルを選びます。パネルが表示されている間は 2 秒ごとに（git が時間のかかるリポジトリではもっと間を空けて）gitを実行し、リポジトリの設定がそのために指定できるプログラム — fsmonitor、外部 diff、テキスト変換 — は実行しません。別のマシンの端末の隣では、ThinkTerm を通じてそちらでgitを実行します。 - 株価（
stocks）は Yahoo Finance のウォッチリストで、銘柄ごとの 1 日の動きを線で示し、選んだ銘柄のチャートを出します。銘柄は、パネル上部のフィールドに打ち込んで Return を押すと加わります。パネルにキーボードがあるとき、上下キーで前後の銘柄を選びます。Yahoo のチャート API は公式のものではなく、予告なく拒否されたり変わったりすることがあります。 - テキストツール（
text-tools）はplugins/exampleにあり、プラグインを書く出発点として置かれています。コマンドラインからの 2 種類の呼び出し、decodeとuuidに答えます。パネルでは、入力したもの — JWT、Unix 時刻、URL エンコード、Base64 — をデコードします。Decode from the terminalを使うと、隣の端末でデコードできる最も下の行をデコードし、結果を入る行数だけ折り返して表示します。
プラグインを書く
プラグインのプログラムは、標準入力と標準出力を通じて、1 行ずつの JSON で ThinkTerm とやり取りします。パネルは手で描きます。プラグインが矩形、テキスト、線、塗りつぶし領域、そしてクリックが届く場所の一覧を送り、ThinkTerm がそれを描きます。テキストは折り返しを指定でき、その場合は箱の高さが許す行数に分けられます。デスクトップもブラウザも同じように分け、収まりきらないときは省略記号で終わります。ウィジェットはありません。
Rust のクレート thinkterm-plugin-sdk がこのプロトコルを実装しており、上のプラグインはどれもこれを使っています。マニフェスト、メッセージ、パネルの要素、各種の上限は、ThinkTerm のリポジトリの docs/thinkterm/plugins.md に詳しく書かれています。開発中は、ソースのディレクトリをプラグインディレクトリにリンクしてビルドし直せば足ります。プログラムが標準エラーに書いたものは、プラグインサーバーのログに入ります。