docs: record CLI runner release and move NeoMutt guidance [skip ci]
This commit is contained in:
1 parent
8733645747
commit
7187af42ed
5 files changed
+54
-111
No files matched your search
@@ -1,5 +1,7 @@
|
||||
# pages-cli:`pages` HTTPクライアント
|
||||
|
||||
2026-11-06:利用者向けの[クライアント契約](https://git.anya.jp/anya/pages-cli/src/branch/main/docs/client-contract.md)と[NeoMutt連携](https://git.anya.jp/anya/pages-cli/src/branch/main/docs/neomutt.md)は独立した公開pages-cliリポジトリへ移転した。本書はサーバー側のHTTP・OIDC認証契約、結合テストと導入履歴を保持する。下記のv0.3.0/v0.4.0は分離前のサーバー同梱版の番号であり、独立CLIはv0.1.0から採番する。
|
||||
|
||||
2026-11-01。合成データで検証済み。同日、本番サーバのCity更新と合わせてクライアントをホストの `/home/anya/.local/bin/pages` に配置した。実ユーザの資格情報取得・ログイン・本番Page編集は未実施。接続設定とログインは利用者が行う。[反映記録](../../operations/deployments/2026-11-01-city-pages-cli.md)。
|
||||
|
||||
v0.3.0のOIDCログインは利用者の動作確認済み。v0.4.0ではOIDC承認時の追加ローカルTOTPを廃止し、CLIの `auto` 言語選択と既存Pageの新規言語版編集を実装した。2026-11-01 21:48 JSTに本番サーバー/PATH上のCLIへ反映済み。[v0.4.0反映記録](../../operations/deployments/2026-11-01-v0.4.0.md)。
|
||||
|
||||
@@ -1,109 +1,10 @@
|
||||
# neomuttとpages CLIによるタスク管理
|
||||
# NeoMutt連携ドキュメントの移転
|
||||
|
||||
メールからタスクを作り、作業の開始・終了を記録し、個人アドレス帳をneomuttの宛先補完に使う。先に通常の端末でpages-cliを設定してログインする。neomuttの設定やシェル履歴にトークンを書かない。
|
||||
NeoMuttとpages CLIによるメールからのタスク作成、作業時間の記録・レポート、日次メール設定、連絡先の宛先補完の利用手順は、独立した公開リポジトリへ移転した。
|
||||
|
||||
```sh
|
||||
pages configure --origin https://pages.anya.jp --username YOUR_USERNAME
|
||||
pages login --oidc --no-browser
|
||||
pages task --help
|
||||
```
|
||||
- [NeoMuttとタスク・連絡先の操作ガイド](https://git.anya.jp/anya/pages-cli/src/branch/main/docs/neomutt.md)
|
||||
- [NeoMutt設定ファイル例](https://git.anya.jp/anya/pages-cli/src/branch/main/examples/neomuttrc)
|
||||
- [CLIの接続・保存・安全性の契約](https://git.anya.jp/anya/pages-cli/src/branch/main/docs/client-contract.md)
|
||||
- [CLIリポジトリと配布物](https://git.anya.jp/anya/pages-cli)
|
||||
|
||||
別接続を使うときは `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` の例。pagesの絶対パスはインストール先に合わせる。件名等をシェルコマンド文字列に展開せず、メールを標準入力で渡す。
|
||||
|
||||
```muttrc
|
||||
set pipe_split = yes
|
||||
set pipe_decode = no
|
||||
macro index,pager ,t "<pipe-message>/home/anya/.local/bin/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 = "/home/anya/.local/bin/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.anya.jp/_/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で送る。詳細は [タスクと連絡先の設計](../design/ja/task-productivity-contacts.md) を参照。
|
||||
利用者向け手順と設定例の正本はpages-cli側とし、このページは既存リンクの移転案内として残す。サーバーAPI・権限・DB・通知ジョブの設計は引き続き[タスクと連絡先の設計](../design/ja/task-productivity-contacts.md)で管理する。PagesWiki側の `pages-cli/` はHTTP結合テスト用の固定スナップショットであり、独立CLIの配布元ではない。
|
||||
@@ -1,6 +1,6 @@
|
||||
# pages-cliの公開リポジトリと配布準備
|
||||
# pages-cliの公開リポジトリと配布
|
||||
|
||||
2026-11-06、サーバー本番をv0.7.1へ更新した後、pages-cliを[公開リポジトリ anya/pages-cli](https://git.anya.jp/anya/pages-cli)へ切り出した。ユーザー指定により公開とし、認証なしでの閲覧を確認した。ソースのpushは完了。CI用runnerの接続待ちで、リリースタグとRelease添付はまだ作成していない。
|
||||
2026-11-06、サーバー本番をv0.7.1へ更新した後、pages-cliを[公開リポジトリ anya/pages-cli](https://git.anya.jp/anya/pages-cli)へ切り出し、[v0.1.0](https://git.anya.jp/anya/pages-cli/releases/tag/v0.1.0)をGitea Actionsから公開した。ソースとLinux/amd64成果物はログイン不要で取得できる。
|
||||
|
||||
## ソースと互換性
|
||||
|
||||
@@ -10,6 +10,8 @@
|
||||
|
||||
独立したローカルリポジトリは `/home/anya/prj/pages/pages-cli` に配置し、originを公開Giteaリポジトリへ接続した。配布準備コミットは `e4fb4f309f9257498af678c3ae37d22039081b15`、公開用の説明修正後のコミットは `e3f1be2f6f99ced3d287cbe2155c3d614b0a133b`。公開前にCLIのみの履歴と追跡対象を確認し、秘密情報候補はテスト用の架空資格情報だった。サーバーの履歴・設定・データは含めない。
|
||||
|
||||
v0.1.0のソースは `7fa71eceb1ecbed84ad3bc904af3f3a473624b92`。NeoMutt連携ガイド、設定例、クライアント契約を独立リポジトリへ移転し、tar.gzにも同梱した。サーバーの旧ドキュメントは移転案内、HTTP/OIDCサーバー内部設計と結合テストはサーバー側に保持する。
|
||||
|
||||
サーバー側の3つのGo結合テストはCLIのスナップショットを参照している。切り出し時点では削除せず、独立リポジトリを正本にした後、レビュー済みリビジョンに固定して明示更新する。サーバーCI中に認証付きgit fetchを増やしたり、最新CLIへ暗黙追従したりしない。DB直接操作CLI `data/pageswiki-cli` は切り出し対象外。
|
||||
|
||||
## 配布方式
|
||||
@@ -22,8 +24,10 @@ macOS用のnative buildジョブはrunner接続後に有効化する。Windows/a
|
||||
|
||||
## 検証と残件
|
||||
|
||||
Linux ELFの生成、ソース単体テスト30件、実ELFのconfigure・合成HTTPログイン・タスク一覧・対話シェル・不正な資格情報ファイル権限の拒否・ログアウトを確認した。SHA256SUMSによる全4生成物の照合も成功した。テストは一時ディレクトリと合成HTTPサーバーのみを使用し、本番ユーザーの資格情報は使用しない。
|
||||
ソース単体テスト32件、実ELFのconfigure・合成HTTPログイン・タスク一覧・メール取り込み時の本文非送信・NeoMutt宛先検索・対話シェル・不正な資格情報ファイル権限の拒否・ログアウトを確認した。テストは一時ディレクトリと合成HTTPサーバーのみを使用し、本番ユーザーの資格情報は使用しない。
|
||||
|
||||
公開コミットからも同じDockerfileでローカルビルドと30件のテスト、実ELFのスモークテストが成功した。Giteaの[初回CI run 29](https://git.anya.jp/anya/pages-cli/actions/runs/29)はqueued。既存のcp01dはwikipagesリポジトリ専用のonline runnerで、pages-cliとanyaユーザーのrunner一覧は空だった。pages-cli専用runnerの追加、またはユーザー共通runnerへの再登録が必要。既存runnerの削除・登録範囲変更は行っていない。
|
||||
既存cp01dのホストにリポジトリ専用の `cp01d-pages-cli` を追加し、[初回CI run 29](https://git.anya.jp/anya/pages-cli/actions/runs/29)、[移転後CI run 30](https://git.anya.jp/anya/pages-cli/actions/runs/30)、[v0.1.0 Release CI run 31](https://git.anya.jp/anya/pages-cli/actions/runs/31)が成功した。既存runnerは変更していない。配置・停止方法は[runner運用記録](pages-cli-runner.md)を参照。
|
||||
|
||||
残件はrunner接続、CI成功確認、v0.1.0タグ・Release添付・匿名ダウンロード検証、macOS runnerの設置、Windows移植とrunnerでの検証。実行ファイルのコード署名、macOS公証、rpm/debは後続。リポジトリ公開はオープンソースライセンスの新規付与とは別の操作であり、独自コードへのライセンスは追加していない。
|
||||
Releaseはジョブtokenで公開でき、追加PATは不要だった。添付5ファイルを匿名ダウンロードし、SHA256SUMS記載の4生成物を照合、ダウンロードしたELFの上記スモークテストを実施した。tar.gz内のREADME・NeoMuttガイド・クライアント契約・設定例がソースと一致し、メタデータのsource_revisionがタグ先コミットと一致することも確認した。
|
||||
|
||||
残件はmacOS runnerの設置、Windows移植とrunnerでの検証。実行ファイルのコード署名、macOS公証、rpm/debは後続。リポジトリ公開はオープンソースライセンスの新規付与とは別の操作であり、独自コードへのライセンスは追加していない。
|
||||
@@ -0,0 +1,34 @@
|
||||
# cp01d上のpages-cli専用runner
|
||||
|
||||
2026-11-06、既存のPagesWiki用runnerを維持したまま、同じcp01ホストへpages-cli用runnerを追加した。Giteaの登録名は `cp01d-pages-cli`、登録範囲は公開リポジトリ `anya/pages-cli` のみ。既存の `cp01d` は `anya/wikipages` 専用のまま変更していない。
|
||||
|
||||
## 配置と起動
|
||||
|
||||
- SSH接続先は既存設定の `cp01`。rootful Dockerを使用する。
|
||||
- Composeは `/var/container/gitea/runner-pages-cli/compose.yml`、プロジェクト名は `gitea-pages-cli`。
|
||||
- コンテナ名は `gitea-pages-cli-runner`、登録情報は `runner-pages-cli/data/.runner`(0600)。配置ディレクトリは0700。
|
||||
- runner設定は `runner-pages-cli/config.yaml`。capacity=1、timeout=2h、TLS検証有効、ジョブのprivileged=false。
|
||||
- イメージは既存と同じrunner v3.5.0のdigest `gitea/runner@sha256:66b7da94dc7dcadb2e076bec6928221336a9a637196399281c4b766fe1288242`。
|
||||
- 既存ネットワーク `anya-npm-net` と `git.anya.jp:172.18.0.10` の名前解決を使用。新規ネットワークやサブネットは作成していない。
|
||||
|
||||
```sh
|
||||
# cp01上で実行。既存のGitea・PagesWiki用runnerには影響しない。
|
||||
sudo docker compose -p gitea-pages-cli \
|
||||
-f /var/container/gitea/runner-pages-cli/compose.yml up -d --no-deps runner
|
||||
|
||||
# 新規ジョブの引受けを止める場合。実行中ジョブを確認してから行う。
|
||||
sudo docker compose -p gitea-pages-cli \
|
||||
-f /var/container/gitea/runner-pages-cli/compose.yml stop runner
|
||||
```
|
||||
|
||||
既存Gitea Composeへの依存を避け、追加runnerだけを独立Composeで管理する。restart=unless-stopped。サーバーや既存runnerの再起動・再登録は不要。既存Gitea用のComposeファイルだけを指定した操作では追加runnerは管理されない。
|
||||
|
||||
## 認証と公開ジョブ
|
||||
|
||||
登録トークンはCLIリポジトリ専用APIで取得し、暗号化SSHの標準入力から登録時の一時コンテナ環境へ渡した。Compose、Git、通常起動時の環境変数に登録トークンは保存しない。登録後は `.runner` を使う。`.runner` はコピー・公開せず、バックアップ時も権限を維持する。
|
||||
|
||||
ジョブラベルは `ubuntu-latest`。公開リポジトリのmain・バージョンタグ・手動実行のみを対象とし、外部PR実行は設定していない。Docker socketを使うため、ジョブにはホストに対する強い権限がある。レビューしていない外部コードをこのrunnerで実行しない。既存runnerとDocker daemonを共有するため、両runnerが同時に各1ジョブを実行できる。今後並列数を増やす場合はCPU・メモリ・ディスク負荷を確認する。
|
||||
|
||||
初回の既存待機ジョブrun 29と、NeoMutt移転後のrun 30が成功した。run 30では32件のテストと実ELFによる合成ログイン、メール→タスク、宛先検索、対話シェル、権限検査、ログアウトを確認した。macOS runnerは未接続のため対応ジョブを無効化している。
|
||||
|
||||
v0.1.0タグのrun 31ではRelease添付と公開も成功した。Giteaのジョブtokenを利用し、追加PATやActions secretは作成していない。公開後の匿名ダウンロードとSHA256照合、実バイナリの合成API試験も成功した。
|
||||
@@ -1,5 +1,7 @@
|
||||
# pages-cli
|
||||
|
||||
このディレクトリはサーバーのHTTP結合テスト用スナップショットです。CLIの配布・新規開発・利用手順の正本は[公開pages-cliリポジトリ](https://git.anya.jp/anya/pages-cli)へ移転しました。[NeoMutt連携ガイド](https://git.anya.jp/anya/pages-cli/src/branch/main/docs/neomutt.md)と[クライアント契約](https://git.anya.jp/anya/pages-cli/src/branch/main/docs/client-contract.md)も独立側を参照してください。
|
||||
|
||||
**`pages` — PagesWikiをターミナルから読む、たどる、編集する。**
|
||||
|
||||
プロファイルや言語は初回に設定し、普段のコマンドは短く保ちます。
|
||||
|
||||
Reference in new issue
Block a user