Move NeoMutt integration guides and client contract into CLI releases
This commit is contained in:
1 parent
e3f1be2f6f
commit
7fa71eceb1
8 files changed
+219
-5
No files matched your search
+115
@@ -0,0 +1,115 @@
|
||||
# neomuttとpages CLIによるタスク管理
|
||||
|
||||
メールからタスクを作り、作業の開始・終了を記録し、個人アドレス帳をneomuttの宛先補完に使う。先に通常の端末でpages-cliを設定してログインする。neomuttの設定やシェル履歴にトークンを書かない。
|
||||
|
||||
```sh
|
||||
pages configure --origin https://pages.example.test --username YOUR_USERNAME
|
||||
pages login --oidc --no-browser
|
||||
pages task --help
|
||||
```
|
||||
|
||||
別接続を使うときは `pages --profile NAME task ...`。保存セッションはprivateなプロファイルファイルを使い、処理中はプロファイルロックを取得する。
|
||||
|
||||
## メールから作成
|
||||
|
||||
```sh
|
||||
pages task from-mail < message.eml
|
||||
pages task from-mail --project '開発 計画' --due 2026-11-03 < message.eml
|
||||
# 本文を保存してよいメールに限り明示する
|
||||
pages task from-mail --include-body < message.eml
|
||||
```
|
||||
|
||||
既定では件名をタスク名、From・Date・Message-IDをメモにする。本文と添付はアップロードしない。include-bodyはplain text本文だけを追加し、HTML画像・添付・外部URLは取得しない。1通2 MiB、メモ16 KiBが上限。件名が300 UTF-8 bytesを超える場合は `--title '短い件名'` で指定する。
|
||||
|
||||
同じ接続・本人・Message-IDから同じrequest_idを作るため、同じメールの再取り込みで重複しない。Message-IDなしはメール全体のSHA-256を使う。同じメールを別の独立タスクにもしたい場合は `task add` を使う。
|
||||
|
||||
`~/.config/neomutt/neomuttrc` の例。NeoMuttから実行するPATHに `pages` を含めるか、コマンドをインストール先の絶対パスに置き換える。件名等をシェルコマンド文字列に展開せず、メールを標準入力で渡す。[設定ファイル例](../examples/neomuttrc)も配布アーカイブに同梱する。
|
||||
|
||||
```muttrc
|
||||
set pipe_split = yes
|
||||
set pipe_decode = no
|
||||
macro index,pager ,t "<pipe-message>pages task from-mail<enter>" "Create PagesWiki task"
|
||||
```
|
||||
|
||||
`,` → `t` で選択メールを取り込む。pipe_splitは複数メールを1つのMIME入力へ連結しないため、pipe_decode=noはCLI側でMIMEを解釈するための設定。既存のpipe操作にも影響するので、自分の設定と合わせて確認する。[NeoMutt設定リファレンス](https://neomutt.org/guide/reference.html)を参照。
|
||||
|
||||
## 通信失敗と再送
|
||||
|
||||
CLIは作成要求を送信前にprivateなセッションファイルへ保持する。失敗時に表示するrequest_idで明示的に再送する。
|
||||
|
||||
```sh
|
||||
pages task retry REQUEST_UUID
|
||||
```
|
||||
|
||||
最大20件を保留でき、成功した要求はローカルから削除する。同じ本人への再ログインで保留分を維持する。別アカウントへ切り替える場合は別プロファイルを使う。認証済みセッションがない状態からの完全オフライン入力受付ではない。
|
||||
|
||||
サーバーで保存された直後に応答が失われても、同じrequest_idで再送すれば既存タスクが返る。保留要求を書き換えて再送すると412になる。セッションファイルにはトークンもあるため、デバッグ目的で内容を貼り付けない。
|
||||
|
||||
## 計画と実績
|
||||
|
||||
```sh
|
||||
pages task project-add '開発 計画'
|
||||
pages task projects
|
||||
pages task preferences --project '開発 計画' --due-days 3 --review-days 1 --estimate 60 --complexity 2
|
||||
pages task add '設計をレビュー' --estimate 120 --planned 2026-11-02
|
||||
pages task list --view today
|
||||
pages task update TASK_UUID --due 2026-11-04
|
||||
pages task start TASK_UUID
|
||||
pages task status
|
||||
pages task stop
|
||||
pages task done TASK_UUID
|
||||
pages task report --from 2026-11-01 --to 2026-12-01
|
||||
pages task report --from 2026-11-01 --to 2026-12-01 --json
|
||||
```
|
||||
|
||||
stopは作業記録の終了、doneはタスクの完了。両者は独立している。見積は分単位、complexityは1〜5。期間のtoは含まない。CSV等への後処理にはJSONを使う。APIはドメインのタイムゾーンで日付を集計する。
|
||||
|
||||
日次メールを設定する例。SMTP設定と本人のメール登録が必要で、CLIを実行しただけでは第三者へ送信しない。
|
||||
|
||||
```sh
|
||||
pages task preferences --digest on --at 09:00 --timezone Asia/Tokyo
|
||||
pages task preferences --digest off
|
||||
```
|
||||
|
||||
## neomuttの宛先補完
|
||||
|
||||
```sh
|
||||
pages contacts list --query 田中
|
||||
pages contacts import contact.vcf
|
||||
pages contacts export CONTACT_UUID > contact.vcf
|
||||
pages contacts query 田中 --neomutt
|
||||
```
|
||||
|
||||
```muttrc
|
||||
set query_command = "pages contacts query --neomutt -- %s"
|
||||
bind editor <Tab> complete-query
|
||||
```
|
||||
|
||||
neomuttは%sをシェル用に引用するので、%sをさらに引用符で囲まない。出力は先頭の状態行と、メール・名前・所属のタブ区切り。`--`は検索語をCLIオプションとして解釈させないために付ける。標準のCtrl-Tによる補完を残したい場合はbind行を省略する。[外部アドレス検索](https://neomutt.org/guide/advancedusage.html#query)、[query_command](https://neomutt.org/guide/reference.html#query-command)。
|
||||
|
||||
連絡先は本人のDomain内だけを検索し、最大100件。メールアドレスのない連絡先は候補に出ない。ログイン切れの場合は通常の端末で再ログインする。書き出したvCardには非公開情報が含まれるため、ファイル権限と保存先を確認する。
|
||||
|
||||
## HTTPクライアントから使う
|
||||
|
||||
`POST https://pages.example.test/_/api/v1/extension/organizer.tasks/capture`
|
||||
|
||||
Content-Typeはapplication/json、AuthorizationはBearerセッション。例示UUIDは要求ごとに生成し、通信再送時だけ同じものを使う。
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "884587b2-6ae5-4aef-86d0-fd21dac39d1c",
|
||||
"title": "メールで依頼された内容を確認",
|
||||
"notes": "Message-ID: <example@example.invalid>",
|
||||
"estimate_minutes": 30,
|
||||
"complexity": 2,
|
||||
"due_on": "2026-11-03"
|
||||
}
|
||||
```
|
||||
|
||||
成功は201とitem。認証切れ401、権限不足403、要求IDの内容競合412、不正入力422。トークンをクエリ文字列に含めず、HTTPSで送る。CLIの接続・保存・安全性は[クライアント契約](client-contract.md)を参照。サーバーのDB・ジョブ・権限の内部設計はサーバーリポジトリで管理する。
|
||||
|
||||
## 接続先とトラブルシューティング
|
||||
|
||||
NeoMuttでは対話ログインを起動せず、端末で先に `pages login` を完了させる。複数接続を使う場合は、メール取り込み・宛先検索の両方を `pages --profile work ...` に揃える。NeoMutt起動環境のHOME・XDG_CONFIG_HOMEが通常の端末と異なると、別の設定やセッションを参照するので確認する。
|
||||
|
||||
`pages: not found` の場合は `command -v pages` でインストール先を確認し、設定内のコマンドをその絶対パスに置き換える。`contacts query` の候補がない場合は、まず端末から `pages contacts list --query 検索語` を実行する。認証切れは端末で再ログインしてから再試行する。公開CLIリポジトリへメール原文・連絡先・セッションJSONを添付しない。
|
||||
Reference in new issue
Block a user