From 7fa71eceb1ecbed84ad3bc904af3f3a473624b92 Mon Sep 17 00:00:00 2001 From: Anya Tokugawa Date: Fri, 6 Nov 2026 07:18:45 +0900 Subject: [PATCH] Move NeoMutt integration guides and client contract into CLI releases --- README.md | 4 +- docs/client-contract.md | 51 ++++++++++++++++++ docs/neomutt.md | 115 ++++++++++++++++++++++++++++++++++++++++ examples/neomuttrc | 14 +++++ test_distribution.py | 12 +++++ test_productivity.py | 9 ++++ tools/build.py | 3 ++ tools/smoke_binary.py | 16 ++++-- 8 files changed, 219 insertions(+), 5 deletions(-) create mode 100644 docs/client-contract.md create mode 100644 docs/neomutt.md create mode 100644 examples/neomuttrc diff --git a/README.md b/README.md index df9d734..8580c85 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ pages edit /guide --lang en # 英語版。未作成なら既存内容から 対応範囲は既存Pageの更新と新規言語版の作成です。新規Path/Page作成、バイナリ更新は未実装です。 競合や通信断で自動上書きせず、ローカル原稿を保持します。HTTPS必須(開発用loopbackのみHTTP可)。 -詳しいURI・保存・安全性の契約はサーバーリポジトリの `docs/design/ja/remote-cli.md` にあります(同リポジトリへのアクセス権が必要です)。 +詳しいURI・保存・安全性の契約は[クライアント契約](docs/client-contract.md)を参照してください。 ## テスト @@ -158,4 +158,4 @@ python3 -m unittest test_pages test_productivity test_distribution `pages task --help` で作成・計画・開始/終了・レポートを操作できる。 `pages contacts --help` で個人アドレス帳の検索・vCard入出力を行える。 -neomutt設定と操作例はサーバーリポジトリの `docs/operations/neomutt-tasks.md` を参照。 +[NeoMutt設定とタスク・連絡先の操作例](docs/neomutt.md)、[そのまま調整して使える設定例](examples/neomuttrc)を参照。これらは配布アーカイブにも同梱します。 diff --git a/docs/client-contract.md b/docs/client-contract.md new file mode 100644 index 0000000..b1ce825 --- /dev/null +++ b/docs/client-contract.md @@ -0,0 +1,51 @@ +# pages-cliの接続と保存契約 + +pages-cliはPagesWikiのHTTPクライアントであり、DBやDocument Storeを直接開かない。実行名は `pages`、独立配布版はv0.1.0から始まる。配布・OS条件は[配布ガイド](../DISTRIBUTION.md)、初期設定とコマンドは[README](../README.md)、メール・タスク・連絡先は[NeoMutt連携](neomutt.md)に記載する。 + +## 接続と認証 + +接続先のoriginでDomainを決め、サーバーの既存認証・権限評価を使う。遠隔接続はHTTPS必須。証明書検証を無効にするオプションはない。HTTPはloopbackでの開発専用。originにuserinfo、Path、query、fragmentを含めず、リダイレクトには追従しない。ログイン画面のHTMLや302/303をAPIの成功として扱わない。 + +パスワードログインでは必要に応じてTOTPを入力する。`login --oidc [--no-browser]` ではブラウザのOIDCログイン後に、ターミナルの確認コードを入力して承認する。S256でCLIのverifierに束縛し、短期リクエストを一度だけBearerセッションへ交換する。SSH先から開始し、別端末で承認できる。ブラウザCookie、外部OIDC token、Campus用PSKをCLIのBearerとして流用しない。 + +OIDC入口はサーバーv0.3.0以降。OIDCで認証した利用者への追加ローカルTOTP省略と新規言語版の編集はサーバーv0.4.0以降。タスク・連絡先を含む独立CLIの利用基準はサーバーv0.6.0以降。独立CLIとサーバーのバージョン番号は連動しない。 + +## ローカル状態と秘密情報 + +設定は `$XDG_CONFIG_HOME/pages-cli/config.json`、セッションは同じルートの `sessions/PROFILE.json` に置く。XDG_CONFIG_HOME未指定時は `~/.config/pages-cli/`。ディレクトリ0700、ファイル0600と所有者を検査し、シンボリックリンクは拒否する。設定とセッションは分離し、atomic replaceとプロファイルロックで保存する。同じプロファイルの同時利用は拒否する。 + +設定のorigin・usernameと保存セッションの対応を検査する。ログイン中の接続先変更はlogoutを先に行う。logoutはサーバーの失効に失敗した場合、成功と報告せず資格情報を残す。パスワード・TOTP・Bearerを引数、URL、履歴、設定表示へ含めない。セッションファイルは平文なので、同じOSユーザーやrootからは保護できない。OS keyringは未対応。 + +## アドレスと編集 + +Pathは到達経路、UUIDはPageの識別子、Revisionは履歴。正本は `/v/raw/path:/...`、`uuid:`、`rev:` で取得する。Wiki正本はHTMLで、編集用Markdownはauthoring射影。children等の展開結果を保存せず、HTMLの保護フェンスを既存変換APIで往復する。 + +編集開始時にObject UUIDと保存先言語、基点Revisionを確定する。`auto` は表示されたRevisionの言語を採用する。明示した言語のheadがなければ既存言語の内容を下書きとして開き、空の基点で新規言語版をCAS保存する。自動翻訳はしない。無変更なら作成しない。編集途中でPathが変わっても別Pageへ保存しない。 + +`$EDITOR` はshellを介さず起動する。作業ファイルは0700の一時ディレクトリ内へ0600で保存し、成功・無変更時は削除する。通信断や競合時は原稿と復旧メタデータを保持して場所を表示する。復旧メタデータにBearerを入れない。競合時は差分を示して停止し、自動マージ・強制上書き・保存要求の自動再送は行わない。 + +`put` は既存言語の基点を `--base` で指定する。新規Path/Page、バイナリ編集、Asset更新は未対応。Revisionアドレスは取得専用。ブラウザで `open` する際はブラウザ自身のログインを使い、共有リンクを自動発行しない。 + +## HTTP API + +| 操作 | エンドポイント | +| --- | --- | +| パスワード・MFA | POST `/_/auth/login`、`/_/auth/totp` | +| OIDC引き継ぎ | POST `/_/auth/cli/start`、ブラウザ `/_/auth/cli/verify`、POST `/_/auth/cli/token` | +| 失効 | POST `/_/auth/logout` | +| 一覧・補完 | GET `/_/api/v1/path-picker` | +| 検索候補 | GET `/_/api/v1/search/suggest` | +| 正本・識別子 | GET/HEAD `/v/raw/{explicit-address}` | +| 編集状態 | GET `/_/api/v1/editor/state` | +| HTMLへの復帰 | POST `/_/api/v1/render/markdown`、authoring=true、projection=false | +| CAS保存 | POST `/_/api/v1/revisions/save` | +| タスク | `/_/api/v1/extension/organizer.tasks/`配下のcapture・items・preferences・work・report | +| 個人アドレス帳 | `/_/api/v1/extension/organizer.contacts/`配下のitems・import | + +## 上限と検証 + +ネットワークには20秒のsocket timeoutと応答サイズ上限がある。総転送時間の厳密なdeadlineや巨大転送のstreamingは未対応。`get` は最大64 MiB、SHA-256を照合し、新規0600ファイルへ出力する。既存ファイルは上書きしない。編集テキストは1 MiB、JSON送信は2 MiBまで。 + +メール取り込みは1通2 MiB、本文は明示指定時のみ、保持するメモは16 KiBまで。再送用要求は最大20件。連絡先importは1枚のUTF-8 vCard、64 KiBまで。NeoMutt検索は本人・Domain内の個人アドレス帳を対象とし、最大100件を返す。 + +CLIの単体・実バイナリ試験は合成データのみを使用する。サーバー側の権限・CAS・OIDC署名検証とGoのHTTP結合テストはPagesWikiリポジトリで管理する。Windowsの資格情報保護とロック移植、新規Page作成、競合の対話的復旧、巨大ファイル転送は後続タスク。 diff --git a/docs/neomutt.md b/docs/neomutt.md new file mode 100644 index 0000000..e1ba60e --- /dev/null +++ b/docs/neomutt.md @@ -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 "pages task from-mail" "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 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: ", + "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を添付しない。 diff --git a/examples/neomuttrc b/examples/neomuttrc new file mode 100644 index 0000000..db5a018 --- /dev/null +++ b/examples/neomuttrc @@ -0,0 +1,14 @@ +# Merge into your own NeoMutt configuration; do not replace unrelated settings. +# Run `pages configure` and `pages login` in a terminal first. +# `pages` must be on NeoMutt's PATH; otherwise use its absolute install path. +# For a named connection, use `pages --profile work ...` in BOTH commands. +# These pipe settings also affect other pipe-message commands. +set pipe_split = yes +set pipe_decode = no +macro index,pager ,t "pages task from-mail" "Create PagesWiki task" + +# NeoMutt quotes %s. Do not add another pair of quotes around it. +# -- prevents a leading dash in the search text from becoming a CLI option. +set query_command = "pages contacts query --neomutt -- %s" +# Optional; omit to keep the standard Ctrl-T binding: +# bind editor complete-query diff --git a/test_distribution.py b/test_distribution.py index 70e70e8..5fe9b6f 100644 --- a/test_distribution.py +++ b/test_distribution.py @@ -1,6 +1,7 @@ import contextlib import io import os +import re from pathlib import Path import runpy import tempfile @@ -10,6 +11,17 @@ import urllib.request from tools.publish import SameOriginRedirect, main class DistributionTests(unittest.TestCase): + def test_documentation_links_and_neomutt_example(self): + root=Path(__file__).resolve().parent + for document in [root/'README.md',root/'DISTRIBUTION.md',*sorted((root/'docs').glob('*.md'))]: + for target in re.findall(r'\]\(([^)]+)\)',document.read_text()): + if '://' in target or target.startswith('#'):continue + self.assertTrue((document.parent/target.split('#',1)[0]).is_file(),(document.name,target)) + example=(root/'examples/neomuttrc').read_text() + self.assertIn('pages task from-mail',example) + self.assertIn('pages contacts query --neomutt -- %s',example) + self.assertNotIn('--include-body',example) + def test_version_matches(self): module=runpy.run_path(str(Path(__file__).with_name('pages'))) self.assertEqual(module['VERSION'],Path('VERSION').read_text().strip()) diff --git a/test_productivity.py b/test_productivity.py index b1c708a..f504ca4 100644 --- a/test_productivity.py +++ b/test_productivity.py @@ -42,3 +42,12 @@ class ProductivityTests(unittest.TestCase): for cmd in [('task','--help'),('contacts','--help'),('task','add','--help')]: with contextlib.redirect_stdout(io.StringIO()),self.assertRaises(SystemExit) as raised:m['main'](list(cmd)) self.assertEqual(raised.exception.code,0) + + def test_neomutt_query_leading_dash_is_data(self): + calls=[] + def query(route): + calls.append(route) + return {'items':[{'name':'Person','emails':['person@example.invalid'],'organization':''}]} + with contextlib.redirect_stdout(io.StringIO()): + m['contacts'](SimpleNamespace(json=query),['query','--neomutt','--','--unexpected']) + self.assertIn('q=--unexpected',calls[0]) diff --git a/tools/build.py b/tools/build.py index c1c91cf..62136fd 100644 --- a/tools/build.py +++ b/tools/build.py @@ -39,6 +39,9 @@ def main(): tar.add(binary,arcname='pages') for path in ('README.md','DISTRIBUTION.md','THIRD_PARTY.md','VERSION'): tar.add(ROOT/path,arcname=path) + for directory in ('docs','examples'): + for path in sorted((ROOT/directory).rglob('*')): + if path.is_file():tar.add(path,arcname=str(path.relative_to(ROOT))) python_license=Path(sysconfig.get_path('stdlib'))/'LICENSE.txt' if not python_license.is_file():raise SystemExit('Missing Python license') tar.add(python_license,arcname='licenses/Python-LICENSE.txt') diff --git a/tools/smoke_binary.py b/tools/smoke_binary.py index 1f9e5fc..ec88caa 100644 --- a/tools/smoke_binary.py +++ b/tools/smoke_binary.py @@ -14,14 +14,19 @@ seen=[] class Handler(BaseHTTPRequestHandler): def log_message(self,*args):pass def do_POST(self): - self.rfile.read(int(self.headers.get('Content-Length',0))) + body=self.rfile.read(int(self.headers.get('Content-Length',0))) if self.path=='/_/auth/login': self.reply({'access_token':token,'token_type':'Bearer','expires_in':3600}) elif self.path=='/_/auth/logout':self.reply({}) + elif self.path=='/_/api/v1/extension/organizer.tasks/capture': + if self.headers.get('Authorization')!='Bearer '+token:self.send_error(401);return + self.reply({'item':json.loads(body)}) else:self.send_error(404) def do_GET(self): if self.headers.get('Authorization')!='Bearer '+token:self.send_error(401);return seen.append(self.path) - self.reply({'items':[{'uuid':'synthetic-task','title':'Packaged CLI task','status':'todo'}]}) + if self.path.startswith('/_/api/v1/extension/organizer.contacts/items?'): + self.reply({'items':[{'name':'Synthetic Person','emails':['person@example.invalid'],'organization':'Test'}]}) + else:self.reply({'items':[{'uuid':'synthetic-task','title':'Packaged CLI task','status':'todo'}]}) def reply(self,value): self.send_response(200);self.send_header('Content-Type','application/json');self.end_headers();self.wfile.write(json.dumps(value).encode()) @@ -38,11 +43,16 @@ try: run('configure','--origin',f'http://127.0.0.1:{server.server_port}','--username','synthetic') run('login',stdin='synthetic-password\n') if 'Packaged CLI task' not in run('task','list'):raise AssertionError('Task missing') + mail='Subject: Mail task\r\nMessage-ID: \r\nContent-Type: text/plain\r\n\r\nPRIVATE BODY' + captured=run('task','from-mail',stdin=mail) + if 'Mail task' not in captured or 'PRIVATE BODY' in captured:raise AssertionError('Mail privacy') + contact=run('contacts','query','--neomutt','--','--name') + if 'person@example.invalid\tSynthetic Person\tTest' not in contact:raise AssertionError('NeoMutt query') run('shell',stdin='pwd\nexit\n') profile=Path(root)/'pages-cli/sessions/default.json' if profile.stat().st_mode&0o077:raise AssertionError('Credential permissions') profile.chmod(0o644);run('task','list',success=False);profile.chmod(0o600) run('logout') if not seen:raise AssertionError('No HTTP request') - print('Packaged CLI: configure/login/task-list/permissions/logout passed') + print('Packaged CLI: configure/login/task-list/mail-capture/neomutt-query/shell/permissions/logout passed') finally:server.shutdown();server.server_close();thread.join()