Files
Anya Tokugawa e27c023d66
Test and release pages-cli / linux (push) Successful in 19s
Test and release pages-cli / macos (push) Skipped
fix: explicitly recreate deleted task captures
2026-11-08 19:26:51 +09:00

171 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 preferences --wiki-prefix /private/mail
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
# このメールだけ保存先の親Pathを変更
pages task from-mail --wiki-prefix /private/work-mail < message.eml
# 本文を送らず、件名とメタデータだけタスクにする
pages task from-mail --metadata-only < message.eml
```
v0.3.0からは件名をタスク名、From・Date・Message-IDをメモにし、**本文を関連Wikiページに保存する**。PagesWiki v0.8.0以降が必要。保存先は `--wiki-prefix`、個人設定の既定Wiki親Path、選択プロジェクトのWiki配下(メモの階層)の順に決まる。どれも未設定なら保存を中止し、下書きを保持する。Webでは `/-/sys/config?panel=organizer` の「メール本文の既定Wiki親Path」で確認・変更できる。CLIで空文字を設定すると個人の既定Pathを解除できる。
本文の公開範囲は保存先Wikiの権限に従う。タスクが個人用でも、公開Pathに保存した本文は公開され得るため、メール用には閲覧者を制限したPathを指定する。設定例の `/private/mail` という名前自体が非公開を保証するものではない。
CLI v0.4.0のメール取り込みにはPagesWiki v0.9.0以降が必要。保存先は次の優先順で決める。
| メール | 保存先 |
| --- | --- |
| 先頭にML連番がある | `親Path/リスト名/連番`(例:`/mail/hogehoge/123`) |
| ML連番なし、Message-IDあり | `親Path/YYYY/MM/UUID` |
| 両方なし | `親Path/YYYY/MM/原文SHA-256` |
リスト名はASCII英数字で始まり、英数字・ピリオド・ハイフン・アンダースコアの100文字以内。連番は最大20桁で、先頭ゼロを除去する。Re:/Fw:/Fwd:の直後も認識し、先頭のML表記を使う。安全なリスト名・連番として解釈できない場合は年月方式へフォールバックする。表示件名の `--title` は保存先の判定を変えない。
年月はDateヘッダに記載されたタイムゾーンの年月。Dateが欠落・不正なら最初の取り込み時点のUTC年月を使い、未送信outboxに確定値を保持する。UUIDは接続先・本人・Message-IDから生成し、Message-ID自体をURLへ露出しない。同じML名・連番に異なるメールが来た場合は409で停止し、既存本文を上書きしない。
既存ページは移動・上書きせず、従来形式で保存済みの要求をretryしても元のページを返す。タスクのメモ閲覧・編集ボタンから本文ページを開ける。タスク・Wiki・再送receiptは同一トランザクションで保存し、途中失敗で片方だけを残さない。UUIDで紐づくので、その後Wikiを移動しても追従する。
CLI v0.3.1ではMIMEヘッダを復号した件名の先頭から `[list 123]`・`[list:123]`・`[list#123]` のような連番を除去する。Re:/Fwd:は維持し、その後の連番も除去する。`[重要]`、件名の途中の括弧、`--title` で明示した件名は変更しない。自動件名が300 UTF-8 bytesを超える場合は文字境界で省略して末尾に「…」を付ける。除去・省略・手動指定で変わった元のSubjectはWiki本文に残す。手動件名の上限超過は拒否する。
plain textを優先し、HTMLしかない場合はテキストを抽出する。添付・外部画像・CSS・JS・外部URLは取得せず、本文中のHTMLやWikiマクロも実行しない。原文EMLやHTMLレイアウトの保存機能ではない。入力1通2 MiB、Wiki本文(メタデータ込み)256 KiB、タスクメモ16 KiBまで。本文・メモの上限超過は切り捨てず拒否する。旧 `--include-body` は既定動作の別名として残す。以前の本文非送信動作には `--metadata-only` を使う。
同じ接続・本人・Message-IDから同じrequest_idを作るため、同じメールの再取り込みで重複しない。Message-IDなしはメール全体のSHA-256を使う。同じIDで本文・指定Path・オプションを変えると412となり、以前のページを上書きしない。旧版でメタデータのみ取り込み済みのメールに本文を追加する場合は、既存の関連Wikiを編集する。同じメールを別の独立タスクにもしたい場合は `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件を保留でき、成功した要求はローカルから削除する。同じ本人への再ログインで保留分を維持する。別アカウントへ切り替える場合は別プロファイルを使う。認証済みセッションがない状態からの完全オフライン入力受付ではない。
CLI v0.4.1以降では、同一内容の保留メールを再入力した場合は、確定済みの保存先を維持する。同じrequest_idで本文・件名・オプションを変更して再入力した場合は、ローカルの保留下書きを新しい内容で上書きしてから1回送信する。送信失敗時も新しい内容を保持する。`task add --request-id` も同じ動作。新しいrequest_idを発行して重複タスクを作る処理ではない。
`task retry` は、その時点で保持されている下書きを変更せずに送信する。下書きを上書きするには、NeoMuttから同じメールを改めて取り込むか、同じrequest_idを指定した `task add` を実行する。旧版で保留していた下書きも対象となる。
サーバーにすでに保存済みの同じ要求に対して本文・保存先・オプションが異なる場合は、従来どおり412で停止する。ローカル下書きの上書きは、保存済みタスクやWikiの強制上書きではない。保存済みの内容を変更する場合は通常のタスク/Wiki編集を使う。
サーバーで保存された直後に応答が失われても、同じrequest_id・同じ内容で再送すれば既存タスクが返る。サーバー保存済みの要求と異なる内容で再送すると412になる。セッションファイルにはトークンと保留中のメール本文があるため、デバッグ目的で内容を貼り付けない。保存先未設定で失敗した場合は `pages task preferences --wiki-prefix /YOUR/MAIL/PATH` で設定してからretryする。
### 削除済みタスクを再取り込みする
CLI v0.4.2/PagesWiki v0.14.1以降の機能です。サーバーとCLIの両方の更新が必要で、CLI v0.4.1/PagesWiki v0.14.0では利用できません。
削除後も重複防止の受付記録は残ります。対応サーバーでは、内容の違いにかかわらず削除済み要求を410 `deleted` で拒否します。通常のretryで復活させず、保留下書きを使った再取り込みは次のように明示します。
```sh
pages task retry REQUEST_UUID --recreate-deleted
```
新しいUUIDのタスクを作成し、旧UUIDの削除記録とCalDAVの識別子予約は残します。同じ操作から生成されるUUIDは一定なので、応答が失われても重複作成しません。旧タスクの完了状態・作業記録・サブタスクを復元する操作ではありません。存続中のタスクをこのオプションで上書きすることもできません。
Wiki保存先にページが残っている場合は、本文・リビジョンを上書きせず新しいタスクに再リンクします。ページがなければ保留本文から作ります。本文の変更は通常のWiki編集で行ってください。保存先の現在権限が必要です。保存先は保持したsuffix/指定prefixと現在の既定値で決まり、移動された元ページを自動追跡する機能ではありません。
CLIは送信前に保留下書きを新IDへ移して保存し、`Retry ID:` に新IDを表示します。通信失敗後は新IDを使い、`--recreate-deleted` を付けずに再送します。
```sh
pages task retry NEW_REQUEST_UUID
```
元のメールを再入力するだけでは削除済みの状態を解除しません。受付記録はあるのにタスクと削除記録が両方ない場合は409 `capture_missing` となり、サーバー側の整合性調査が必要です。受付記録・削除記録を手動削除して回避しないでください。
## 計画と実績
```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>",
"wiki_body": "メール本文をテキストとして保存",
"wiki_prefix": "/private/mail",
"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が通常の端末と異なると、別の設定やセッションを参照するので確認する。
自己署名証明書の検証環境ではv0.2.0以降の `pages -k login`、`pages -k task from-mail`、`pages -k contacts query --neomutt -- %s` が使える。`-k` は保存されないため、ログインとNeoMutt設定内の各コマンドに明示する必要がある。警告は標準エラーへ出力し、宛先候補の標準出力には混ぜない。配布設定例は検証有効のままとする。相手の真正性が保証されなくなるリスクと適用範囲は[README](../README.md#自己署名証明書の環境に接続する)を確認する。
`pages: not found` の場合は `command -v pages` でインストール先を確認し、設定内のコマンドをその絶対パスに置き換える。`contacts query` の候補がない場合は、まず端末から `pages contacts list --query 検索語` を実行する。認証切れは端末で再ログインしてから再試行する。公開CLIリポジトリへメール原文・連絡先・セッションJSONを添付しない。