本文へ移動
anya's wiki

PagesWikiをブラウザとターミナルから使いやすくする

2026年11月1日。今日は、前日から進めていた操作系の改善を本番へ反映しつつ、リモートCLIとOIDCによるログインを実装した。

PagesWikiは、HTMLをマスタとし、用途に応じてMarkdownなどの編集形式や各種ビューアへ射影するWiki。 URLのPathで文書をたどり、Knowledge City ModelではQuartier、Street、Spotとして整理する。

機能は増えてきたが、毎回メニューを開いて操作するのは面倒。

今回は、検索して、移動して、そのまま編集するまでの手数を減らすことを中心に進めた。

ブラウザの中でもcdする

ファイルブラウザに、Pathのアドレスバーとコマンドバーを設けた。

アドレスバーはトップバーに統合し、コマンドバーは画面左下に配置している。

cd /manual
vi /manual/start
view /manual/start

cd はディレクトリ移動、vi は編集画面、view は閲覧画面へ進む。

OSのシェルを実行するものではなく、PagesWikiのPathを操作するためのコマンドだ。TabでPathを補完でき、相対Pathも扱える。

ファイルブラウザでは、ほかの入力欄にフォーカスしていなければ、文字を打つとコマンドバーへ入力が入る。

共通ナビゲーションのあるほかの画面では、g でコマンドバーを呼び出す。エディタ内のVim操作やフォーム入力は奪わない。

ホーム画面だけは用途が違うので、文字を打つとグローバル検索へ入るようにした。

まず検索したい場所と、Pathをたどりたい場所で操作を分けている。

まだ文書のないPathへ、仮想フォルダとして潜ることもできる。

空フォルダの実体を先に作る必要はなく、移動先から新規文書の作成やアップロードへ進める。

モバイルでは幅のあるアドレスバーを隠し、一覧を優先する。

エディタとビューアの色をそろえる

エディタのライトモードとカーソル表示を見直した。

Vimの通常、挿入、置換、選択のモードに合わせてカーソルを変え、現在行や選択範囲もテーマに追従する。

シンタックスハイライトは、エディタ、コードファイルのビューア、文書中のコードブロックで共通のテーマ色を使うようにした。

編集するときと読むときで、同じコードの見え方が大きく変わらないようにするためだ。

文書中のコードブロックは、画面に見えてきたものから処理する。 大きすぎるブロックや未対応言語は原文のまま表示し、ハイライトのために保存済みHTMLを書き換えることはしない。

共通ナビゲーションにはテーマの切り替えも追加した。

プリセットをその場で選べ、リロードは不要。これはブラウザ単位の上書きで、ドメイン全体の既定テーマを変更する操作ではない。

PlainTextも扱う

HTMLやMarkdownとして解釈してほしくない文書のために、PlainTextモードを追加した。

新規作成時に選択でき、既存の text/plain もそのまま編集できる。

PlainTextでは、保存もプレビューも文字列として扱う。

HTMLタグやマクロを書いても実行しない。既存WikiをPlainTextへ変換する操作は、情報が失われる可能性があるため、今回の範囲には含めていない。

ターミナルから使うpagesコマンド

リモートクライアントを pages-cli というサブプロジェクトに整理し、コマンド名を pages にした。

pages configure --origin https://pages.example.test --username anya
pages login
pages

pages だけで対話シェルに入る。普段使う接続先や言語は設定に保持するので、毎回プロファイル名や言語を引数へ並べなくてよい。

pages[default]:/> cd /manual
pages[default]:/manual> ls
pages[default]:/manual> edit start

ls、cd、cat、view、get、edit、put、search、open などを実装した。PathのTab補完と、上下キーでのシェル内履歴にも対応している。ワンショットなら pages edit /manual/start のように使える。

view はローカルの $PAGER、edit は $EDITOR を使う。普段のVimでWikiを編集し、表示が難しいものは open でブラウザへ渡せる。ブラウザを開くために文書を勝手に公開したり、共有リンクを発行したりはしない。

既存のDB直接操作用CLIとは別物で、こちらはHTTP経由の利用者向けクライアントだ。Webと同じ認証・権限評価を受け、サーバのSQLiteやファイルストアを直接開かない。Pythonの標準ライブラリで動くUnix系環境向けの初期版としている。

VimでMarkdownを書いてもマスタはHTML

Wikiを edit すると、既定では編集用Markdownをローカルエディタへ渡す。保存時は、既存のauthoring変換APIを通してHTMLへ戻す。

ここで大事なのは、編集用と閲覧用を分けること。たとえば children マクロは、閲覧時には子ページの一覧になってほしいが、編集時にその一覧へ展開して保存されると困る。CLIでもこの区別を維持し、マクロを含む文書を編集用の表現で往復させる。

HTMLをマスタにする考え方は変えていない。Markdownを使うために保存形式全体をMarkdownへ寄せるのではなく、HTMLの柔軟性を保ちつつ、書きやすい形式を入口として選ぶ。HTMLそのものを編集したければ --format raw も使える。

保存には編集開始時のRevisionを渡す。ほかの端末で更新されていれば競合として止め、ローカルの原稿を残す。初期版は既存ページの更新が対象で、新規作成や競合時の対話的なマージは次の段階だ。

CLIのOIDCログインも実装

パスワードとTOTPに加えて、ブラウザでOIDC認証を行い、CLIへセッションを引き継ぐ機能も実装した。こちらは本稿執筆時点では実装・検証済みで、本番反映待ち。サーバとCLIの両方を対応版へ更新する必要がある。

pages login --oidc

SSH先など、ブラウザを自動で開きたくない場合は次の形にする。

pages login --oidc --no-browser

ターミナルに表示されたURLをPCやスマホで開き、OIDCでログインする。その後、接続先とアカウントを確認し、ターミナルに出ている確認コードを入力して承認すると、CLIが専用のセッションを受け取る。ローカルTOTPが設定されていれば、その検証も行う。

CLI側で待ち受けポートを開く必要はない。外部IdPのパスワードやトークンをCLIへ渡すこともなく、ブラウザのCookieをコピーする方式でもない。

引き継ぎリクエストは5分で失効し、交換は一度だけ。S256による照合、承認画面のCSRF対策、交換時のアカウント・セッション失効確認を入れた。URLに長期Bearerを載せず、ログインしただけでCLIへの承認が完了することもない。他人から送られたURLやコードを、そのまま承認してはいけない。

Device Flowに近い操作感だが、実装はPagesWiki専用のセッション引き継ぎであり、汎用のOAuth Device Authorization Serverを実装したという話ではない。

Cityの検索結果はコンテンツへ

Knowledge City Modelの検索結果も整理した。QuartierやStreet、Spotが見つかったとき、まず欲しいのは管理設定ではなく、そこにある文書だと思う。

対応するPathにページがあればその本文へ、なければ配下のディレクトリ一覧へ進むようにした。検索サジェストも同じ導線にそろえている。

自動生成された未整理Spotの Undefined 表示も見直した。既定のプレースホルダー名は親Streetの表示名を使い、独自に付けたタイトルは保持する。UUIDやPath境界を書き換えるものではなく、閲覧時の表示を整える変更だ。

名前を読みやすくするために所属や権限まで変わるのは困る。表示名、識別子、到達先を分けて扱い、検索先のページや配下の要素でも閲覧権限を確認する。

連絡先とセッション期限

プロフィールに電話連絡先を追加した。番号をタップすると tel: スキームで端末の対応アプリへ渡せる。

電話番号は既定で非公開とし、プロフィールそのものの公開設定とは分けた。プロフィールを公開しただけで電話番号まで出ることはない。公開範囲を広げる場合は明示的に確認し、プロフィールやドメイン側の公開制限も適用する。

セッションの有効期間もドメインごとに設定できるようにした。これは新しく発行するセッションの絶対期限で、無操作タイムアウトとは別。既存セッションやCalDAVのアプリパスワードの期限を一括変更するものではない。

機能追加と一緒に基盤も整理

内部構成は8つのコンポーネントへの初期分離を進め、今日までの変更をv0.2.0としてまとめた。あわせて、イベントログ保存時のSQLite書き込み競合をv0.2.1で修正した。

ジョブ本体は成功しているのに、開始ログだけが保存できない状態があった。ログの読み取り後に書き込みへ移る方式を改め、書き込み権を確保してから生ログと集約値を同じトランザクションで保存するようにした。待機と再試行には上限を設け、ログ保存の失敗だけで成功済みのジョブを再実行しないようにしている。

本番反映後の短時間の観察では、完了した57件のジョブすべてに開始・完了ログがあり、修正前に起きていたログ保存競合は再現しなかった。長時間の観察は引き続き必要だが、機能を足すだけでなく、何が実行されたか追える土台も整えておきたい。

次に進めること

今日の時点では、ブラウザ操作、編集・テーマ、Cityの導線、連絡先、パスワード認証のリモートCLIは反映済み。ログ競合修正もv0.2.1で反映した。OIDCのCLI引き継ぎはv0.3.0向けの実装として、本番適用と実IdPでの確認を残している。

次はCLIの Ctrl+P によるfuzzy検索、新規ページ作成、競合時の選択操作を進めたい。実機の日本語IMEやiPhone Safariでの細部も確認していく。

ブラウザ、ローカルのVim、ターミナル。それぞれ別のデータを持つのではなく、同じ文書とPathを、それぞれ使いやすい入口から扱えるようにしていく。