CLI で esa.io の記事を作成するツール esautils を作りました

開発の動機

最近 esa.io を業務で使うようになりました。とても便利です。
ブラウザでの編集も快適なのですが、年中端末に引き篭っている身からすると、どうにか CLI でも記事を更新をしたいと思っていました。

例えば CLI で esa.io の記事更新ができるようになると、以下のようなことができるようになります。

• vi/emacs などお気に入りのエディタを使って編集できる
• screen/tmux など端末プレクサとのコピペが楽になる
• 他の CLI ツールと連携しやすくなる
• cron などで記事更新を自動化できる

既存の esa.io 関連ツール

公式のライブラリとして esa-ruby があります。

サードパーティ製の esa.io ツールは以下のページでまとめられています。

• https://docs.esa.io/posts/158

CLI ツールとしては esa-cli がありますが、記事の観閲がメインです。
esa.vim のようなエディタのプラグインを使えばローカルでも記事作成はできますが、他の CLI ツールとの連携には使えません。

esautils

概要

CLI で記事の投稿・更新をするためのコマンド群です。
記事の取得もできますが、検索のためのコマンドはありません。

言語は Go 言語を使用しました。
ライブラリとしては upamune さんの go-esa を利用させていただきました。

設計思想

esautils では記事のNumberごとにディレクトリを作成し、その直下に JSON キーと対応するファイルを配置します。

例えば esa.io の API からの応答は以下のような JSON です。

{
  "number": 1,
  "name": "hi!",
  "full_name": "日報/2015/05/09/hi! #api #dev",
  "wip": true,
  "body_md": "# Getting Started",
  "message": "Add Getting Started section",
  "tags": [
    "api",
    "dev"
  ],
  "category": "日報/2015/05/09",
}

これを JSON のキーごとに個別のファイルに書き出します。
esa_new というコマンドで記事を作成すると以下のようなファイルが作成されます。

$ esa_new "日報/2015/05/09" "hi!"
$ ls -F
$ 352/
$ tree 352/
352/
├── BodyMd
├── Category
├── Message
├── Name
├── Tags
└── Wip

それぞれのファイルの内容は単なるテキストファイルです。

• BodyMd: 記事の本文 (Markdown記法)
• Category: カテゴリ
• Message: 記事作成・更新の際のメッセージ
• Name: 記事タイトル
• Tags: タグ (改行区切り)
• Wip: WIPフラグ (true or false)

環境変数

各コマンドの使用前にいくつかの環境変数を設定する必要があります。

• ESA_API_KEY
  • アプリケーショントークン
• ESA_TEAM
  • esa.io のチーム名
• ESA_USER
  • ユーザ名

API KEYの取得は以下のURLから行うことができます。

• https://your_team.esa.io/user/applications

各コマンドの使い方

• esa_new CATEGORY NAME
  • 説明:
    • 新規に記事を作成する
  • 引数:
    • CATEGORY: 記事カテゴリ
    • NAME: 記事タイトル
• esa_update NUMBER
  • 説明:
    • 記事を更新する
  • 引数:
    • NUMBER: 記事のNumber (esa_newが作成したディレクトリ名を指定)
• esa_attach PATH
  • 説明:
    • 添付ファイルをアップロードする
  • 引数:
    • PATH: アップロードするファイルのパスを指定
  • 返り値:
    • アップロード先のURL
• esa_get NUMBER
  • 説明:
    • 指定したNumberの記事を取得する
  • 引数:
    • NUMBER: 記事のNumber
• esa_getall
  • 説明:
    • 自分のユーザ名に紐付く全ての記事を取得する

esa_newやesa_getで記事の作成・取得を行い、ローカルで編集した後、esa_updateで更新する、という流れを想定しています。

使用例

(1) fswatchとの連携

fswatchがファイルの更新を検知する度に自動で esa.io の対応記事をアップデートします。

#!/bin/bash
fswatch --one-per-batch -d -0 . | while read -d "" path; do
  POST_NUM=`basename $(dirname $path)`
  PATTERN="[0-9]+"

  diff $POST_NUM/BodyMd{.draft,} && continue
  cp $POST_NUM/BodyMd{.draft,}

  if [[ $POST_NUM =~ $PATTERN ]]; then
    esa_update $POST_NUM
  fi
done