Files
pages/docs/design/ja/remote-cli.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
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.
2026-11-01 15:23:31 +09:00

11 KiB
Raw Blame History

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する。外部カレンダーや本番資格情報は使わない。

次段階の順序:

  1. Ctrl+Pによる検索選択、補完の引用文字/途中カーソル対応、永続履歴の明示opt-in。
  2. 新規Page+Path+初回Revisionの原子的な作成API、create/upload-only権限、並行作成の衝突、言語分岐。
  3. 競合の対話選択・復旧コマンド、巨大転送のstreamingとキャンセル、mget/mput(globのlocal/remoteを明示)。
  4. OIDCブラウザ認証の短命・単回・PKCE相当ハンドオフ。既存device approvalをそのまま転用せず、本人確認・Domain・CLIリクエストを束縛する。
  5. OS keyring、Windows対応、非公開の短縮リンク引き継ぎ。自動的な公開shareは行わない。