Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
11 KiB
pages-cli:pages HTTPクライアント
2026-11-01。合成データで検証済み。同日、本番サーバのCity更新と合わせてクライアントをホストの /home/anya/.local/bin/pages に配置した。実ユーザの資格情報取得・ログイン・本番Page編集は未実施。接続設定とログインは利用者が行う。反映記録。
原設計との整合
原設計の Address Model、URI、認証バックエンド、エディタの保存契約を使用する。
- Pathは到達経路、UUIDはPageの識別子、Revisionは履歴。取得は
/v/raw/path:/...、uuid:、rev:で行い、/raw/...を増設しない。 - 編集開始時にObject UUIDを確定し、指定言語のheadを取得。保存はUUID+言語+
base_revision_uuid+editor_principal_uuid。Path変更に追従するため保存先を再解決して別Pageに書き込まない。 - Wiki正本はHTML。編集用Markdownはauthoring射影であり、children等の表示展開結果を保存しない。保護HTMLフェンスを既存authoring APIで往復する。
- Domainは接続originで決まり、HTTPで既存の認証・権限制御を受ける。Campus連携用トークン/PSKをユーザー認証に流用しない。
- 旧認証設計にはCookie中心の記載が残るが、実装済みのJSONログインはBearerセッションを発行する。CLIはこのフローを使用し、Web Cookieを抽出しない。
data/pageswiki-cliは信頼されたローカル運用ツールとして維持。遠隔版はサブプロジェクトpages-cli、実行名pages(pages-cli/pages)とし、DB・Document Storeを直接開かない。
サーバAPI/DBスキーマの追加・変更はない。初期実装はPython 3.9以降の標準ライブラリで動作するUnix系クライアント(fcntl、readline使用)。Windowsネイティブ版は未対応。
利用方法
# 初回設定。パスワードはlogin時の非表示プロンプト、必要ならTOTPを続けて入力。
pages configure --origin https://pages.example.test --username anya
pages login
pages status
pages
# ワンショット。--lang はコマンドより前に指定する。
pages ls /manual
pages edit /manual/start
pages get /manual/start ./start.html
pages put ./start.html /manual/start --base REVISION_UUID
pages logout
配置方法と詳しい設定例は pages-cli README。既定プロファイル名は default、編集言語は und。pages configure --lang ja で変更し、configure set --profile work --origin ... --username ... --lang en で接続先を追加する。configure use work で既定を切り替え、通常操作ではprofile/langの引数を省略する。一時的な --profile/--lang 上書きも残す。
設定は config.json の version/default_profile/profiles と、各接続のorigin/username/langに限定。パスワード・Bearerは設定表示へ含めない。configureはネットワーク通信をせず、ログイン中のorigin/username変更を拒否する。mainは設定ロック→セッションロックの順で取得し、起動時の接続先すり替えを防ぐ。手編集時も保存したセッションの接続先・アカウントとの一致を確認してから使用する。logoutは設定を手編集した場合でも、保存済みの元接続先に対して失効する。
対話シェルは ls、cd、pwd、status、cat、view、get、put、edit、search、open、logout、exit を扱う。--help で一覧、edit --help 等で引数を確認する。cd は仮想Pathにも移動でき、存在や閲覧可能な子の存在を保証しない。
TabはPath候補を取得し、上下キーは当該プロセス内の履歴をたどる。Pathに空白等があればシェルと同様に引用する。履歴はディスクへ保存しない。現在Pathは接続プロファイルへ保存する。同じプロファイルの同時実行はロックで拒否し、別プロファイルは独立して使える。
search QUERY は権限付きサジェストを表示する初期コマンド。Ctrl+Pのインクリメンタルfuzzy選択は未実装であり、通常のreadlineキー割当のまま。
閲覧・編集
get ADDRESS LOCALは最大64 MiBの正本を取得し、SHA-256を照合する。ローカル出力は0600で新規作成し、既存ファイルを上書きしない。Revision UUIDを表示する。catはpipe時に正本バイト列を出力。TTY時には制御文字を除去する。viewはテキストを$PAGER(既定less)に渡し、HTMLを端末上で実行しない。editは$EDITOR(既定vi)をshellを介さず起動。HTMLはauthoring Markdownが既定、その他の対応テキストは原文。--format rawでHTMLを直接編集できる。--format markdownはHTML文書専用。- ローカル作業ファイルは0700の一時ディレクトリ内に0600で保存。成功・無変更時は削除、失敗/409/通信断時は原稿とrecovery.jsonを保持して場所を表示する。recovery.jsonにはorigin、UUID、基点Revision、言語、形式を記録し、Bearerは含めない。
- 409では最新内容とローカル原稿の差分を表示し、保存は停止する。自動マージ、強制上書き、自動再送はしない。応答喪失時は取得してサーバの状態を確認してから再試行する。
putは既存Pageの既存言語のみ。--baseが必須で、現在headと不一致なら送信しない。サーバ保存も同じbaseでCASを行う。編集を保持したい場合は最新を取得して差分を確認し、調整済み原稿とその最新Revisionを明示して保存する。put --format markdownはauthoring変換を使用。rawは正本形式を保持する。ローカル拡張子で保存MIMEを勝手に変更しない。テキスト編集は1 MiB、JSON送信は2 MiBまで。rev:は取得専用。新規Page、未作成の言語head、バイナリ編集、Asset更新は拒否する。新規作成のためにエディタGETの副作用を利用しない。openは同一originのPath/UUID/Revisionビューアをブラウザで開く。BearerはURLに含めず、ブラウザ側のログインが必要。共有リンクは自動発行しない。
HTTP契約
| 操作 | 既存エンドポイント |
|---|---|
| ログイン/MFA | POST /_/auth/login、/_/auth/totp、フォーム本文+Accept application/json |
| 失効 | POST /_/auth/logout、Bearer |
| 一覧・補完 | GET /_/api/v1/path-picker?mode=children&path=...&prefix=... |
| 検索候補 | GET /_/api/v1/search/suggest?q=... |
| 正本・識別子 | GET/HEAD /v/raw/{explicit-address}?lang=... |
| 言語別編集状態 | GET /_/api/v1/editor/state?uuid=...&lang=... |
| HTMLへの復帰 | POST /_/api/v1/render/markdown、authoring=true、projection=false |
| CAS保存 | POST /_/api/v1/revisions/save |
一覧は既存の件数制限を維持し、truncatedを表示する。巨大な全階層を再帰取得しない。読み取りのRaw言語選択は既存サーバの候補選択に従うが、編集は指定言語のheadを必須とし、存在しない場合は拒否する。
セキュリティと運用上の制限
- 遠隔はHTTPS必須、証明書検証を無効化するオプションなし。HTTPはlocalhost/127.0.0.1/::1の開発専用。
- 接続先はoriginのみ。userinfo、Path、query、fragmentを含むURLは拒否。リダイレクトは同一originも含め追従しない。認証画面HTMLや302/303を成功と扱わない。
- 設定は
$XDG_CONFIG_HOME/pages-cli/config.json、セッションは同じルートのsessions/PROFILE.json(既定~/.config/pages-cli/)。ディレクトリ0700/ファイル0600、所有者を検査し、シンボリックリンクは拒否。atomic replaceとプロファイルロックを使用。旧試作の~/.config/pageswiki-remote/は自動読込・移行・削除しない。再configure/loginし、不要な旧セッションはサーバ側で失効する。 - 資格情報は平文のため、同一OSユーザーやrootからは保護できない。OS keyring/暗号化保存は後続。共有端末ではlogoutし、残した作業原稿は利用者が整理する。
- パスワード/TOTP/Bearerを引数や履歴へ入力させない。保存したexpiryを超えたセッションでは操作を開始せず、実際の失効・権限はサーバで毎回判定する。logout失敗時は失効済みと報告せず資格情報を残す。
- ネットワーク要求には20秒のsocket timeoutと応答サイズ上限。総転送時間の厳密deadline/ストリーミング巨大ファイル対応は後続。
検証と次段階
Python unittest:origin制限、端末制御文字、別origin redirect遮断、非JSON/403/サイズ上限、TOTP、資格情報権限・symlink・並行実行拒否、authoring/CAS payload、ダウンロード上書き拒否、409時の原稿保全。
設定追加後は12件:既定値/複数接続切替/言語保存、一時上書き、設定表示からのトークン除外、セッション保持中の再接続先変更拒否、手編集での接続先不一致拒否も検査。HTTP統合試験では公開エントリーポイントのconfigure→login→引数省略のls/status/edit→logoutを通す。
Goの TestRemoteCLIHTTPIntegration:一時DBと本物のHTTPハンドラでログイン、一覧、編集状態、authoring変換、保存、古いRevision拒否、Rawハッシュ、immutable拒否、存在しない言語拒否、put、ログアウト後の拒否を検査。Pythonがないビルド環境ではこの統合試験をskipする。外部カレンダーや本番資格情報は使わない。
次段階の順序:
- Ctrl+Pによる検索選択、補完の引用文字/途中カーソル対応、永続履歴の明示opt-in。
- 新規Page+Path+初回Revisionの原子的な作成API、create/upload-only権限、並行作成の衝突、言語分岐。
- 競合の対話選択・復旧コマンド、巨大転送のstreamingとキャンセル、mget/mput(globのlocal/remoteを明示)。
- OIDCブラウザ認証の短命・単回・PKCE相当ハンドオフ。既存device approvalをそのまま転用せず、本人確認・Domain・CLIリクエストを束縛する。
- OS keyring、Windows対応、非公開の短縮リンク引き継ぎ。自動的な公開shareは行わない。