プラグイン

abg にコマンドを足したり、ページの Markdown を整えたりするローカルの JavaScript プラグインを、入れて管理し、自作します。

プラグインを入れる

GitHub リポジトリ、git の URL、ローカルのディレクトリから入れます。プラグインのコードは任意の JavaScript なので、--yes が必須です。

abg plugin install user/repo --yes
abg plugin install https://github.com/user/repo.git --yes
abg plugin install git@github.com:user/private-plugin.git --yes
abg plugin install ./my-plugin --name my-plugin --yes

Gateway が読み込んだか確かめます。
Terminal window
```
abg plugin list --loaded
```
コマンドを実行します。プラグインのコマンドは、プラグイン名をサブコマンドにして呼びます。
Terminal window
```
abg my-plugin greet --name "Ada"
```

リポジトリからのインストールには、手元の git コマンドを使います。非公開リポジトリでは、既存の SSH 鍵、git の認証情報ヘルパー、GitHub CLI と連携した git 認証がそのまま使えます。ABG は GitHub のトークンを求めず、保存もしません。認証情報を埋め込んだ HTTPS の URL は拒否します。

プラグインを管理する

abg plugin list
abg plugin update
abg plugin update my-plugin
abg plugin disable my-plugin
abg plugin enable my-plugin
abg plugin reload my-plugin
abg plugin uninstall my-plugin

update は、git で入れたユーザープラグインに git pull --ff-only を実行します。
disable はプラグインのディレクトリを残したまま、コマンドと変換の読み込みを止めます。この状態はアプリのデータベースではなく、使用中の ABG ユーザーディレクトリにある plugin-state.json に保存します。
reload は動作中の Gateway でプラグインを読み込み直します。共有中のタブはそのまま残ります。

コマンドプラグインを作る

ファイルを2つ置いたディレクトリを作ります。
```
hello-plugin/
  index.js
  plugin.json
```
index.js は必須です。plugin.json は省略できますが、一覧表示と --help に使われます。

plugin.json にプラグインの情報を書きます。

{
  "name": "hello-plugin",
  "version": "0.1.0",
  "description": "Minimal ABG command plugin.",
  "commands": [
    {
      "name": "greet",
      "description": "Return a greeting.",
      "args": [
        { "name": "name", "type": "string", "required": false, "default": "ABG" }
      ]
    }
  ]
}

index.js でコマンドを登録します。

abg.registerCommand("greet", async function (args) {
  const name = args.name || "ABG";
  return { ok: true, message: "Hello, " + name };
});

入れてから、コマンドを実行します。

abg plugin install ./hello-plugin --name hello-plugin --yes
abg plugin reload
abg hello-plugin greet --name "Ada"

{
  "message": "Hello, Ada",
  "ok": true
}

編集のたびに abg plugin reload hello-plugin を実行します。読み込みに失敗した場合は、直前のバージョンが動き続けます。

引数はいくつかの形で渡せます。

abg hello-plugin greet --name "Ada"
abg hello-plugin greet --tab t1
abg hello-plugin greet --json '{"name":"Ada"}'
printf '{"name":"Ada"}' | abg hello-plugin greet --stdin

--tab、--tab-id、--match-url、--match-title、--first はコマンドを共有タブに結び付けるためのもので、プラグインには渡りません。コマンドの結果は JSON です。ハンドラーが失敗すると、error、message、plugin、command を含む JSON のエラーが返ります。監査ログにはプラグイン名、コマンド名、引数のキー、引数のバイト数を記録し、引数の値は記録しません。

共有タブを操作する

コマンドのハンドラーは context.tab.<action>(options) で、結び付いたタブを操作できます。呼び出しは CLI と同じ Gateway の経路を通るため、共有、承認、監査ログの仕組みがそのまま働きます。

abg.registerCommand("clear-and-paste", async function (args, context) {
  if (context.tabId == null) {
    return { ok: false, error: "no_tab_context" };
  }
  await context.tab.clear({ selector: args.selector });
  await context.tab.paste({ selector: args.selector, value: args.value });
  return { ok: true };
});

使えるメソッドは CLI のコマンドに対応する paste、clear、fill、click、key、read、describe、wait、screenshot、navigate です。JavaScript からシェルを呼んで別の経路でブラウザーに触れてはいけません。

タブを指定せずにコマンドを実行し、plugin.json に domains があると、ABG は URL が一致する共有タブ 1つにコマンドを結び付けます。一致するタブがなければ no_matching_tab を、複数あれば candidates 付きの ambiguous_tab を返します。

ドメイン専用の Markdown 変換を足す

変換は、文字列を受け取って文字列を返す同期関数です。

abg.log("loaded " + abg.plugin.name);

abg.registerTransform("gmail-clean-markdown", function (input) {
  return String(input).trim();
});

plugin.json に対象ドメインと変換名を書きます。

{
  "name": "gmail-plugin",
  "domains": ["https://mail.google.com/*"],
  "transforms": ["gmail-clean-markdown"]
}

共有タブの URL が domains に一致すると、abg read --format markdown はまずプラグインの変換を試し、次に汎用の html-to-markdown 変換に戻ります。変換名には markdown を含めてください。

リファレンス

プラグインの読み込み元

ABG は次の順にプラグインを探します。

Agent Browser Gateway.app/Contents/Resources/plugins/ に同梱のプラグイン。
~/.abg/plugins/ に入れたユーザープラグイン。
リポジトリから実行しているときは、リポジトリ内の開発用プラグイン。

ポート 8766 の開発版 Gateway は ~/.abg/plugins/ の代わりに ~/.abg-dev/plugins/ を使うため、本番と開発でプラグインの状態が混ざりません。

同梱プラグイン

markdown-plugin: 汎用の HTML から Markdown への変換。
notion-plugin: notion.so と notion.site のページ向けの Markdown 変換。
gmail-plugin、slack-plugin、linear-plugin: ドメイン専用の Markdown 変換の例。slack-plugin は catch-up、pending、open-channel のコマンドも足します。
redaction-plugin: abg read --format markdown --redact で使う任意のマスク処理。
workflow-plugin: context.tab.* を使うコマンドの例。
info-plugin: 読み込みの動作確認用。

作り方の詳細は docs/PLUGINS.md にあります。