ぽよメモ

レガシーシステム考古学専攻

deanishe/awgoを使って簡単にAlfred Workflowを作る

はじめに

 これはGo3 Advent Calendar 2019,7日目の記事です.

qiita.com

Alfred Workflowとは?

 macOS向けの多機能ランチャーであるAlfredの自動化のためのプラットフォームです.Alfredとは,簡単に言ってしまうとmacOSのSpotlightの機能強化版です.

www.alfredapp.com

 過去に以下のようなものを作りました.

poyo.hatenablog.jp

poyo.hatenablog.jp

poyo.hatenablog.jp

最後の一つはAlfredのUIを一切使っていないので少し毛色が違いますが,上2つの様な,

  1. 何らかのトリガーとなるコマンドに対して
  2. 選択肢を提示し
  3. ユーザの選択によって何かアクションを起こす

というものを作りたくなったときに便利に使えます.なお,Alfred本体は無料なのですが,それとは別にPowerPackと呼ばれる拡張パッケージを購入することで使えるようになります.現在のメジャーバージョンでのみ使えるSingle License(25ユーロ),永久ライセンスのMega Supporter(45ユーロ)という二つの形態のライセンスがあるのでお好きな方を購入してください.

www.alfredapp.com

Alfred Workflowの仕組み

 様々な形態のWorkflowがありますが,基本的には用意されているコンポーネントGUIで繋いでいき,あるコンポーネントから別のコンポーネントへ,文字列を受け渡して様々なアクションを起こします.

 自作のスクリプト/バイナリを使ってAlfredのUIを使用したい場合,Script Filterというコンポーネント内でそのスクリプト/バイナリを実行し,所定の形式を持つJSON*1を標準出力へprintします.そのJSONをAlfredが読み取り,良い感じにUIを表示して,選択されたオブジェクト(の中の,次のコンポーネントへ渡す引数となる文字列)を接続されているコンポーネントへ受け渡します.

 実行できるアクションには様々な物があり,

  • ブラウザで検索
  • URLを開く
  • 任意のアプリケーションで開く
  • 任意のスクリプトを実行する

などなど,多数のアクションが用意されています*2.こうしたアクション以外にも,クリップボードへコピーしたり,通知をだしたりも出来ます.便利ですね.

Alfred WorkflowとGo

 Alfred Workflowで動かすアプリケーションをGoで書くというアプローチは,数年前から行われています.

techblog.kayac.com

blog.tsub.me

kyokomi.hatenablog.com

これらのサイトでも述べられていますが,

  • シングルバイナリになるので簡単に配布して簡単に使える

という部分が最も大きいです.全てをシェルスクリプトで書ける猛者ならまだしも,どんなモジュールが入っているか分からないPythonPerlで頑張るよりも簡単かつ安全かと思います.

github.com/deanishe/awgo

 今までは自分の手で書いたstructをjson.Marshal()していましたが,便利なライブラリが開発されていました.

github.com

Alfred3および4用のライブラリで,どちらでも使うことが出来ます*3

 また,表示するアイテムの出力だけでなく,様々な機能のサポートが含まれています.長くなるので今回は紹介しませんが,一通り調べてみたので機会があればそれについても記事を書きたいと思っています.

チュートリアル

以下の環境で実行しています.

  • macOS 10.15
  • Go 1.13
  • Alfred 4.0.6
  • github.com/deanishe/awgo v0.21.0

あまり良い題材を思い浮かばなかったので,今回はこのAlfred Workflowで使った依存パッケージのライセンスを閲覧できるAlfred Workflowを作ってみようと思います.ビルドしたバイナリを配布する場合,使用した各モジュールのライセンスに則って著作権表示等が必要となります*4

f:id:pudding_info:20191206182837g:plain
選択したモジュールのLICENSEを表示

リポジトリはこちら

github.com

1. 空のWorkflowを作る

左下の+からBlank Workflowを選択すると新しいWorkflowを作成するウィンドウが開きます.

f:id:pudding_info:20191205224816p:plain
Blank Workflow

Bundle idはとにかく一意な値であれば良いので,自分の持っているドメイン等があればそこから適当な値を自分で考えれば良いと思います.ここで記述した内容は後からでも変更可能なので,あまり迷う必要はありません.

2. 実行するアクションを並べる

 依存パッケージとライセンスの取得には以下のパッケージを利用させて頂きます.

github.com

これは出力方式としてJSONを選択することができ,その場合各モジュールの名前とLICENSEファイルの中身を取得できます.閲覧のためにはその中身を一旦ファイルに出力する必要があるので,以下の様な構成とします.

  1. モジュール名とライセンスファイルの中身から表示するアイテムを作成するスクリプトを実行
  2. 選択したモジュールのライセンスが文字列で渡されるので,これをWorkflow内のテンポラリディレクトリに出力
  3. そのファイルを規定のプログラムで開く

加えて,Modifierを使ったときの例も示したいので,1の後にCommand + Enterを押すことでそのモジュールのURLをブラウザで開く,というタスクも追加します.

コンポーネントは,右クリックして出てきたメニューから選択して作成できます.各コンポーネント間はドラッグで紐付けることが出来ます.虫のマークはデバッグコンポーネントで,そのコンポーネント間でやりとりされる引数や変数を見ることが出来ます.

f:id:pudding_info:20191206163051p:plain
コンポーネント一覧
コンポーネントの設定はそのコンポーネントをダブルクリックで開けます.

f:id:pudding_info:20191205230549p:plain
Script Filterの設定

f:id:pudding_info:20191205230746p:plain
Write Text Fileの設定

Open File,Open URLコンポーネントはデフォルトのままです.Command+Enterでアイテムを選択したときにOpen URLへ動作を分岐させる方法は,コンポーネント間の接続(エッジ)をダブルクリックすると出てくるメニューから,使用するModifierにチェックを入れるだけです.他のModifierもあるので,更に様々な操作を行うことが出来ます.

3. info.plistを手に入れる

次に,左にあるWorkflow一覧から,このWorkflowを選び,オプションメニューからFinderで開くを選択します.

f:id:pudding_info:20191206163352p:plain
Open in Finder

info.plistというファイルがあると思うので,それを次に作るGoのプロジェクト内にコピーします.このファイルを単体で編集するのは骨が折れるので,基本的にコンポーネントの操作等はAlfredのUI上で行い,それをその都度Goのプロジェクトへコピーするようにしています.

4. Goでプログラムを書く

 まずはプロジェクトを作り,deanishe/awgoをインストールします.

$ mkdir sample-alfred-workflow
$ cd sample-alfred-workflow
$ go mod init
$ go get github.com/deanishe/awgo

Songmu/gocreditsが吐くJSONは以下の様なフォーマットなのでそれに合わせてstructを作ります.

{
  "Licenses": [
    {
      "Name": "モジュール名",
      "URL": "URL",
      "FilePath": "ファイルパス",
      "Content": "LICENSEの中身"
    }
  ]
}

license.goとして以下の内容を記述します.特に難しいところは無いはずです.

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
)

// 各モジュールごとのLicenseを表すstruct
type license struct {
    Name     string
    URL      string
    FilePath string
    Content  string
}

// モジュールごとのライセンスを全て内包するstruct
type licenseJson struct {
    Licenses []license
}

// 与えられたパス名からライセンスを読み取り,ライセンスの一覧を返す
func getLicenses(path string) ([]license, error) {
    contents, err := ioutil.ReadFile("./credits.json")
    if err != nil {
        return nil, fmt.Errorf("%s does not exists.\n", path)
    }
    var licenses licenseJson
    if err = json.Unmarshal(contents, &licenses); err != nil {
        return nil, fmt.Errorf("Failed to parse %s.\n", path)
    }
    return licenses.Licenses, nil
}

ようやくdeanishe/awgoを使ってメインのロジックを書いていきます.とは言っても,この程度のAlfred Workflowならば非常に簡単になります.

package main

import (
    "fmt"
    "os"
    "strings"

    aw "github.com/deanishe/awgo"
)

var (
    // このプロジェクト全体で参照するaw.Workflow
    wf *aw.Workflow
)

func init() {
    // 初期化時にインスタンスを生成する
    wf = aw.New()
}

func run() {
    licenses, err := getLicenses("./credits.json")
    if err != nil {
        // wf.Fatal~~は,エラーメッセージを出力して終了させる
        wf.FatalError(err)
    }
    for _, c := range licenses {
        // ループを回して一つずつItemを作っていく
        // Itemの持つ各メソッドはItem自身を返すのでメソッドチェーンで書ける
        item := wf.NewItem(c.Name).
            // Argは選択されたときに次のコンポーネントへ渡す引数となる文字列
            Arg(c.Content).
            Subtitle(strings.Split(c.Content, "\n")[0]).
            // Valid(true)としないと選択できないので注意
            Valid(true)
        // そのアイテムがCommand+Enterで選択されたときの動作を変更する
        item.Cmd().
            Arg(c.URL).
            Subtitle(fmt.Sprintf("Open %s in browser", c.URL)).
            Valid(true)
    }
    // 与えられた文字列でアイテムをフィルタリングする
    args := os.Args
    if len(args) > 1 {
        // https://godoc.org/github.com/deanishe/awgo/fuzzy
        wf.Filter(args[1])
    }
    // 最終的に表示すべきアイテムが無かったときに表示するエラー文
    wf.WarnEmpty("No credits were found.", "Try different query.")
    // 標準出力へ最終的なJSONをプリントする
    wf.SendFeedback()
}

func main() {
    // 内部でpanic等をうまくハンドリングしてくれる
    wf.Run(run)
}

wf.NewItem()を呼び出した時点で表示するアイテム一覧の中にそのアイテムが追加されるため,どこかにappendしたりする操作は不要です.

6. パッケージングする

 ググっているとAlfredのUI上からExportしないとAlfred Workflowとしては動作しないというように言われていますが,実は.alfredworkflowというファイルの実態は単なるzipファイルです.そのため,単に必要なファイルを全てzipでアーカイブにして拡張子を変えるだけで済みます.今回は以下の様なMakefileを用意しました.

SHELL := /bin/bash

PLIST=info.plist
CREDITS=credits.json
EXEC_BIN=sample-alfred-workflow
DIST_FILE=sample.alfredworkflow
GO_SRCS=$(shell find -f . \( -name \*.go \))

all: $(DIST_FILE)

$(CREDITS): go.sum
  gocredits -json . > $(CREDITS)

$(EXEC_BIN): $(GO_SRCS)
  go build -o $(EXEC_BIN) .

$(DIST_FILE): $(EXEC_BIN) $(CREDITS) $(PLIST)
  zip -r $(DIST_FILE) $(PLIST) $(CREDITS) $(EXEC_BIN)

単にmakeとするだけでsample.alfredworkflowが生成されます.

$ make
# 関連付けされているのでAlfredが開いてインストールできるはず
$ open sample.alfredworkflow

7. CI/CDする

 GitHub Actionsが正式リリースになっているのでこれを使いましょう..github/workflows/release.yamlとして保存します.

name: Release
on:
  push:
    tags:
      - "v*"
jobs:
  release:
    runs-on: macos-latest
    steps:
      - name: Checkout source codes
        uses: actions/checkout@v1
        with:
          fetch-depth: 1

      - name: Setup Go environment
        uses: actions/setup-go@v1
        with:
          go-version: 1.13

      - name: Restore cache if available
        uses: actions/cache@v1
        id: cache
        with:
          path: ~/go/pkg/mod
          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-go-

      - name: download modules
        if: steps.cache.outputs.cache-hit != 'true'
        run: go mod download

      - name: Build
        run: make

      - name: Create new release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

      - name: upload release asset
        id: upload-release-asset
        uses: actions/upload-release-asset@v1.0.1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: ./sample.alfredworkflow
          asset_name: sample.alfredworkflow
          asset_content_type: application/zip

これでタグを付けると以下の様にリリースされます🎉

f:id:pudding_info:20191206181142p:plain
First release!

macOSのセキュリティ

 Catalinaでは,署名されていない,インターネットからダウンロードしたバイナリの実行をデフォルトでブロックします.そのため,この方法でAlfred WorkflowをGitHub Releasesからダウンロードすると以下の様に警告を吐かれます.

f:id:pudding_info:20191206181331p:plain
警告その1

システム環境設定 > セキュリティとプライバシーから実行を許可して再度実行するとまた警告が出ます.

f:id:pudding_info:20191206181521p:plain
警告その2

ここで「開く」を選択すると,ようやく次からAlfred Workflowを使用できます.
別にマルウェアなどは仕込んでいないので安心してください……

deanishe/awgoの微妙なところ

  • 何もかもstructなのでテストしづらい
    • aw.Workflowがあらゆるビジネスロジックを担っている巨大structなので剥がしづらい
    • 小さいInterfaceを自分で定義していくのがいいかも

  • グローバルなaw.Workflowを使い回す設計なのでテストしづらい
    • wf.Run(fn func())の中で実行することを想定しているので,この設計以外で使えない

  • wf.SendFeedback()がDIの機構を持たないので出力をテストしづらい
    • 直接stdoutに書き込んでいて外側からインジェクション出来ない
    • wf.Feedback.MarshalJSON()で生成されるJSONをテストするだけで凌ぐ…?

  • wf.NewItem()がgoroutine safeじゃない
    • 内部的には全てのアイテムはwf.Feedbackが管理しており,wf.NewItem()wf.Feedback.NewItem()を呼んでいる
    • FeedbackのItemsに単に作ったItemをappendしており,goroutineで普通に叩くと壊れる https://github.com/deanishe/awgo/blob/master/feedback.go#L421
    • 普通にaw.NewItem()みたいなのとwf.AddItem()みたいなのがあれば十分だったと思う

  • wf.NewItem()が返すItemがデフォルトでvalid=falseになっている
    • valid=falseなオブジェクトはUIに表示できるが選択できない(エラーメッセージとかを表示するのに使う)
    • デフォルトがfalseなのはAlfredの文脈的には直感に反する
    • 作者の意見:github.com

紹介しきれていない機能

リポジトリに上がっている参考実装がかなりためになります.https://github.com/deanishe/awgo/tree/master/_examples

などなど

まとめ

  • Alfred WorkflowをGoで書くならdeanishe/awgoは機能が豊富で便利
  • GitHub ActionsでCI/CDも出来る
  • macOS Catalinaのセキュリティ機能はかなりおせっかい
  • deanishe/awgoは癖が強いのでテストはちょっと色々考える必要がある

皆さんの面白いAlfred Workflowをお待ちしています.


*1:www.alfredapp.com

*2:www.alfredapp.com

*3:Alfred2まではJSONではなくXMLを使って居ました.これはdeprecatedになっています.Alfred3および4はJSON形式に対応しています https://www.alfredapp.com/help/workflows/inputs/script-filter/xml/

*4:加えてGoの自体のライセンス(BSD3条項ライセンス)も含める必要があります.これ知らなかったので,今後気をつけます…