moonraker-bosun 0.1.0

data/docs/design.md

@@ -0,0 +1,358 @@
+# トラッキングの設計
+
+ホスト側の設定ファイルのトラッキング状態を、gitでどのように記録・運用するかを定める。
+
+## 基本方針
+
+* ホストから取得した内容だけを積み重ねる`host-tracking`ブランチを用意し、これ自体をトラッキングの記録とする
+  * いわゆるvendor branchと同じ考え方
+  * マニフェストファイルなど、トラッキング用の別のデータは持たない
+* ローカルでの編集は`main`ブランチで行い、`host-tracking`を`main`にマージして取り込む
+* 削除は明示的な操作をしない限り行わず、警告と手順の案内にとどめる
+
+```
+host-tracking:  H1 ── H2 ── H3 ─────── H4        ← ホストから取得した内容
+                  \      \      \        \
+main:           ── M1 ─ M2 ─ L1 ─ M3 ─ L2 ─ M4   ← ローカルでの編集(L)とhost-trackingのマージ(M)
+```
+
+## ブランチ
+
+| ブランチ | 内容 |
+| --- | --- |
+| host-tracking | ホストから取得した内容のみ。ツリーには`config/`と`backup/`だけを置く |
+| main | 作業用のブランチ。ツールのコードやドキュメントもここに置く |
+
+* `host-tracking`の先頭のツリーが、トラッキング中のファイルの一覧と、最後に取得した内容を表す
+  * トラッキング中のファイル: `git ls-tree -r --name-only host-tracking -- config/`
+  * 最後に取得した内容: `host-tracking`の先頭にある各ファイルのblob
+* `host-tracking`の履歴が、ホストのスナップショットの列になる
+* `host-tracking`ブランチも`main`と同様にリモートリポジトリにpushする
+  * リモートへのpushはツールでは行わず、gitで行う(`git push origin main host-tracking`)
+
+### 不変条件
+
+以下は常に守る。`audit`で検査する。
+
+1. `host-tracking`の祖先に`host-tracking`以外のコミットを含めない
+   * `main`を`host-tracking`にマージしない
+   * `host-tracking`へのコミットの親は、`host-tracking`の先頭のコミットのみとする
+   * 理由: `main`のコミットが`host-tracking`の祖先に入ると、`host-tracking`を`main`にマージしたときに、`host-tracking`のツリーにない`lib/`などが「削除された」と判断されて消えてしまう
+2. `host-tracking`のツリーには`config/`と`backup/`以外を置かない
+3. `host-tracking`には、ホストから実際に取得した内容だけをコミットする
+   * `push`の後も、アップロードした内容ではなく、取得し直した内容をコミットする
+4. `host-tracking`へのコミットは、作業ツリーとindexを使わずに作成する
+   * ローカルでの変更と混ざらないようにするため
+
+## host-trackingへのコミット
+
+### 作成方法
+
+一時的なindexファイルを使い、plumbingコマンドで作成する。
+
+1. `GIT_INDEX_FILE`に一時ファイルを指定し、`git read-tree host-tracking`で`host-tracking`の先頭のツリーを読み込む
+2. 取得したファイルを`git hash-object -w --no-filters`でblobにし、`git update-index --index-info`で置き換える
+   * `--no-filters`により、`.gitattributes`などによる改行コードの変換を行わず、ホストのバイト列をそのまま記録する
+   * 削除する場合は`git update-index --force-remove`
+3. `git write-tree`でツリーを作成する
+4. `git commit-tree -p host-tracking`でコミットを作成する
+5. `git update-ref refs/heads/host-tracking <新しいコミット> <元のコミット>`で`host-tracking`を更新する
+   * 元のコミットを指定して、途中で`host-tracking`が変わっていた場合には失敗させる
+
+`host-tracking`が存在しない場合(初回)は、1を省略し、4で親を指定しない(orphan)。
+5では元のコミットに空文字列を指定して、`host-tracking`が存在しないことを確認する。
+
+3で作成したツリーが`host-tracking`の先頭と同じ場合は、コミットしない。
+この場合、`Host-File`の`modified`は更新されない(「HとTの比較方法」を参照)。
+
+### コミットメッセージ
+
+機械的に読み取れるよう、形式を固定する。
+
+```
+pull: 2 files
+
+Host-Op: pull
+Host-File: config/printer.cfg modified=1728620000.123 size=4321
+Host-File: config/moonraker.conf modified=1728610000.456 size=1234
+```
+
+* 1行目は`<操作>: <件数> files`(1件の場合は`file`)
+* `Host-Op`は`add`、`pull`、`push`、`backup`、`forget`、`rm`のいずれか
+* `Host-File`は、そのコミットで取得・削除したファイルごとに1行
+  * `modified`と`size`は、Moonrakerのファイル一覧から得たホスト側の値
+  * ホスト側の時刻を使うので、ローカルとホストの時計のずれの影響を受けない
+  * 削除の場合は`deleted`とする
+* `Host-DB`は、Moonraker DBのバックアップのファイルごとに1行(`Host-DB: backup/moonraker-db/mainsail.json`)
+  * DBには更新日時やサイズがないので、パスだけを記録する
+
+## mainへのマージ
+
+* `host-tracking`へのコミットの後、`host-tracking`を現在のブランチにマージする
+  * 現在のブランチが`host-tracking`の場合はエラーにする
+  * `host-tracking`は常に`main`に含まれないコミットを持つので、fast-forwardにはならない
+  * 不変条件が崩れていた場合に備えて、`--no-ff`を必ず付ける(fast-forwardすると、現在のブランチのツリーが`config/`だけになる)
+* 共通の祖先がない場合(初回)は、`--allow-unrelated-histories`を付ける
+* マージコミットのメッセージは`Merge host-tracking (<操作>: <変更したパス>, ...)`とする
+  * 変更したパスがない場合(未マージのコミットだけを取り込む場合)は`Merge host-tracking (<操作>)`
+  * gitに記録するデータなので、表示の言語によらず英語にする
+* ホストからの取得の前に、次の場合は中止する
+  * detached HEADの場合、マージの途中の場合
+  * ステージ済みの変更がある場合(`git merge`は、indexに変更があると対象のファイルと関係がなくても中止するため)
+  * 次のファイルに、作業ツリーの変更やgit管理外のファイルがある場合
+    * 今回取得するファイル
+    * `host-tracking`にあって、まだ現在のブランチに取り込んでいない変更のファイル
+* マージで衝突した場合は、マージを中断した状態で終了し、gitの通常の手順で解決するよう案内する
+  * `host-tracking`へのコミットは完了しているので、取得し直す必要はない
+* 衝突以外の理由でマージできなかった場合も、`host-tracking`へのコミットは残し、`git merge --no-ff host-tracking`を案内する
+
+## 状態の判定
+
+ファイルごとに、次の3つを比べて状態を判定する。
+
+* H: ホストの現在の内容
+* T: `host-tracking`の先頭の内容(最後に取得した内容)
+* L: 現在のブランチの`HEAD`の内容
+
+Tがある(トラッキング中の)ファイル:
+
+| H | L | 状態 | 案内 |
+| --- | --- | --- | --- |
+| Tと一致 | Tと一致 | 同期済み | なし |
+| Tと不一致 | Tと一致 | ホストで変更 | `pull` |
+| Tと一致 | Tと不一致 | ローカルで変更 | `push` |
+| Tと不一致 | Tと不一致 | 両方で変更 | `pull`でマージしてから`push` |
+| なし | あり | ホストで削除 | トラッキングをやめるなら`forget` |
+| なし | なし | 両方で削除 | トラッキングをやめるなら`forget` |
+| `rw`でない | - | ホストで書き込めなくなった | Web UIやSSHで確認する。トラッキングをやめるなら`forget` |
+| Tと一致 | なし | ローカルで削除 | ホストからも削除するなら`rm`、ローカルに戻すなら`git restore --source=host-tracking --staged --worktree -- config/<file>`でコミット |
+| Tと不一致 | なし | ホストで変更、ローカルで削除 | `pull`で取り込んでから判断する |
+
+Tがない(トラッキングしていない)ファイル:
+
+| H | L | 状態 | 案内 |
+| --- | --- | --- | --- |
+| なし | あり | ローカルで追加 | `push`でホストに作成 |
+| あり | あり | 両方にある | `add`で取り込んでマージする |
+| あり(除外しないファイル) | なし | トラッキングしていない | トラッキングするなら`add` |
+
+* Lは`HEAD`の内容なので、未コミットの変更は判定に含めない
+  * `status`では、`config/`の未コミットの変更を別に表示する
+* `host-tracking`に、まだ現在のブランチに取り込んでいないコミットがある場合、TとLの比較は正しくない
+  * `status`では警告し、`git merge --no-ff host-tracking`を案内する
+* ホスト側での名前の変更は、「ホストで削除」と「トラッキングしていない」の組として現れる
+  * 内容が同じもの(Tのblobと、トラッキングしていないファイルのハッシュが一致するもの)を組にして、`add <新しい名前>`と`forget <古い名前>`を案内する
+  * サイズが同じトラッキングしていないファイルだけを取得して比べる
+
+### HとTの比較方法
+
+* 簡易(`status`)
+  * ファイル一覧の`modified`・`size`と、そのファイルを最後に記録した`Host-File`の値を比べる
+    * どちらも一致すれば、一致とする(取得しない)
+    * `size`が違えば、不一致とする(取得しない)
+    * それ以外(`modified`だけが違う、記録がないなど)は、取得して厳密に比べる
+  * 内容が同じまま更新日時だけが変わったファイルは、一致と判定される
+    * そのファイルは、内容が変わって次にコミットされるまで、`status`のたびに取得する
+  * 更新日時とサイズが同じまま内容が変わった場合は検知できない(`audit`で検知する)
+* 厳密(`audit`、`push`、`rm`)
+  * ホストからファイルを取得し、`git hash-object --stdin`で求めたハッシュとTのblobのハッシュを比べる
+
+## 対象のファイル
+
+Moonraker APIの動作は @docs/moonraker-api.md を参照。
+
+### 書き込みの方針
+
+`bosun`がホストに書き込む(アップロード・削除する)のは、Moonrakerが`permissions`を`rw`と報告するファイルだけとする。
+
+* ファイルの種類(シンボリックリンクかどうかなど)ではなく、`permissions`だけで判断する
+  * 現在の環境では、シンボリックリンク(`mainsail.cfg`、`timelapse.cfg`)が`rw`でないファイルに該当する
+  * シンボリックリンクへのアップロードはリンク先を書き換えてしまうが、この方針で防がれる
+* `rw`でないファイルを更新・削除する必要があるときは、`bosun`を使わず、Web UIやSSHで行う
+* `push`と`rm`では、書き込む直前の一覧で`rw`であることを確認する
+  * ローカルで追加したファイルを`push`する場合、ホストに同名のファイルがあれば(`rw`かどうかにかかわらず)中止する
+
+### 一覧とトラッキングの対象
+
+`config`の次のファイルは、`ls`では表示せず(`-a`で表示)、`add`ではエラーにする。
+
+* `permissions`が`rw`でないファイル
+  * 書き込めないファイルをトラッキングしても、`push`できないため
+* ホスト側で作られるバックアップファイル
+  * `SAVE_CONFIG`によるもの: `<名前>-YYYYMMDD_HHMMSS.cfg`
+  * Moonrakerによるもの: `.<名前>.bkp`
+
+`get`では、これらも取得できる(シンボリックリンクはリンク先の内容になる)。
+
+## 印刷中の判定
+
+* `print_stats.state`が`printing`または`paused`の場合は印刷中とする
+* `print_stats`が空の場合(Klipperが`ready`でない場合)は、印刷中ではないとする
+* Moonrakerに接続できない場合は、判定できないので中止する
+
+## コマンド
+
+| コマンド | git | 処理 |
+| --- | --- | --- |
+| `roots` | なし | ホストのRootディレクトリの一覧を表示する |
+| `ls` | なし | ホストのファイル一覧を表示する |
+| `get` | なし | ホストのファイルをカレントディレクトリに取得する |
+| `add` | `host-tracking`へコミット、マージ | 指定したファイルを取得してトラッキングを始める |
+| `pull` | `host-tracking`へコミット、マージ | トラッキング中のファイルを一括で取得する |
+| `status` | 読み取りのみ | 状態を簡易な方法で判定して表示する |
+| `audit` | 読み取りのみ | 状態を厳密な方法で判定し、不変条件も検査する |
+| `diff` | 読み取りのみ | `push`で反映する内容を表示する(`git diff host-tracking HEAD -- config/`) |
+| `push` | `host-tracking`へコミット、マージ | ローカルでの変更をホストに反映する |
+| `forget` | `host-tracking`へコミット、マージ | トラッキングをやめる。ホストのファイルは削除しない |
+| `rm` | `host-tracking`へコミット、マージ | ホストのファイルを削除し、トラッキングをやめる |
+| `backup` | `host-tracking`へコミット、マージ | Moonraker DBの内容を`backup/moonraker-db/`に取得する |
+| `export` | 読み取りのみ | ある時点のスナップショットをディレクトリに書き出す |
+
+### pull
+
+* トラッキング中のファイル(`host-tracking`の先頭のツリーにあるファイル)をすべて取得し、`host-tracking`へコミットしてマージする
+  * 内容が変わったファイルがなければコミットしない
+  * コミットする場合は、取得したすべてのファイルの`Host-File`を記録する(内容が変わっていないファイルの更新日時も記録し直される)
+  * `host-tracking`に未マージのコミットがあれば、変更がなくてもマージする
+* 次のファイルは取得せず、マージの前に警告して手順を案内する
+  * ホストで削除されたファイル(`host-tracking`からは除かない)
+  * ホストで`rw`でなくなったファイル
+  * トラッキングしていないファイル(除外しないもの)
+
+### push
+
+1. `add`や`pull`と同じく、作業ツリーとindexの状態を確認する(「mainへのマージ」を参照)
+   * `config/`のすべてのファイルについて、未コミットの変更やgit管理外のファイルがないこと
+   * `host-tracking`に未マージのコミットがないこと
+2. 印刷中でないことを確認する(「印刷中の判定」を参照)
+3. 反映の対象を決める
+   * Lにあり、Tと異なるファイルを対象にする
+     * Tにもあれば更新、Tになければ作成
+   * 次のファイルは対象にせず、状態と手順を案内する
+     * ローカルで削除したファイル(`rm`などを案内する)
+     * ホストだけで変更・削除されたファイル(`pull`などを案内する)
+4. 対象のファイルについて、反映できるかを確認する
+   * 共通: Lのモードが`100644`(通常のファイル)であること
+     * シンボリックリンク(`120000`)をそのまま反映すると、リンク先のパスの文字列がファイルの内容になる
+     * `host-tracking`にはホストの内容を通常のファイルとして記録するので、実行可能ファイル(`100755`)などを反映すると、マージでモードが衝突する
+   * 更新: ホストにあり、`rw`で、HとTが厳密な方法で一致すること
+   * 作成: ホストに同名のファイルがない(`rw`かどうかにかかわらず)こと、ホスト側のバックアップファイルと同じ形式の名前でないこと
+   * 1件でも反映できないファイルがあれば、何も反映せずに中止し、理由と手順を案内する(終了コードは1)
+5. 書き込む直前にファイル一覧を取得し直し、4の後にホストで変わっていないことを確認する
+   * 更新: `rw`のままで、`modified`と`size`が4で確認したときと同じこと
+   * 作成: まだホストにないこと
+   * 1件でも変わっていれば、何も反映せずに中止する
+6. ファイルをアップロードする
+   * Moonrakerの`checksum`(SHA-256)を付け、内容が壊れた場合は書き込ませない
+7. アップロードしたファイルを取得し直して、`host-tracking`へコミットする
+   * 取得した内容が反映した内容と違う場合は、警告して取得した内容を記録する(不変条件3)
+8. `host-tracking`を現在のブランチにマージする
+9. 設定を有効にするための再起動(RESTARTなど)は行わず、案内だけを表示する
+
+アップロードの途中で失敗した場合(Ctrl-Cなどのシグナルによる中断を含む)は、それまでにアップロードしたファイルだけを取得し直して`host-tracking`にコミット・マージしてから、エラーで終了する。
+反映していないファイルは、もう一度`push`すれば反映できる。
+
+`--dry-run`(`-n`)では4までを行い、反映する内容を表示する。
+
+5の確認から6のアップロードまでの間にホストで起きた変更は防げないが、印刷中でないことを確認しているので許容する(「未決事項」を参照)。
+
+### diff
+
+* `git diff host-tracking HEAD -- config/`を表示する
+  * 最後に取得した内容との差分であり、ホストの現在の内容との差分ではない
+  * 未コミットの変更は含めない
+* ファイルを指定すると、そのファイルに限る。`--stat`で概要だけを表示する
+
+### forget
+
+* 指定したファイルを`host-tracking`のツリーから除いてコミットし、マージする
+  * マージによって、現在のブランチからも削除される
+  * コミットメッセージには`Host-File: <パス> deleted`を記録する
+* ホスト側のファイルは削除しない
+  * ホストには接続しないので、ホストがオフラインでも実行できる
+* 次の場合は中止する
+  * トラッキングしていないファイルを指定した
+  * `add`と同じ作業ツリーの確認(「mainへのマージ」を参照)で問題がある
+  * ローカル(`HEAD`)で変更されている(マージで変更と削除が衝突するため)
+    * ローカルで削除したファイルは指定できる
+
+### rm
+
+* `forget`と同じ確認に加えて、次のことを確認してから、ホストのファイルを削除する
+  * 印刷中でないこと
+  * ホストにあり、`rw`で、HとTが厳密な方法で一致すること(最後に取得した後の変更を失わないようにするため)
+  * 1件でも問題があれば、何も削除せずに中止する
+* 削除する直前にファイル一覧を取得し直し、確認の後にホストで変わっていないことを確認する(`push`と同じ)
+* 削除した後、`host-tracking`のツリーから除いてコミットし、マージする
+  * 削除の途中で失敗した場合(Ctrl-Cなどのシグナルによる中断を含む)は、削除できたファイルだけを記録してから、エラーで終了する
+* `--dry-run`(`-n`)では確認までを行い、削除するファイルを表示する
+
+### backup
+
+* Moonraker DBのnamespaceごとに、内容を`backup/moonraker-db/<namespace>.json`に取得し、`host-tracking`へコミットしてマージする
+  * キーを辞書順に並べた、整形したJSONで保存する(Moonrakerが返すキーの順が変わっても差分が出ないようにする)
+  * 内容が変わらなければコミットしない
+* `config/`と同じく、トラッキングの考え方で扱う
+  * バックアップしているnamespaceは、`host-tracking`の`backup/moonraker-db/`にあるファイルの一覧で表す
+  * `bosun backup <namespace>...`: 指定したnamespaceを取得する(バックアップを始める)
+  * `bosun backup`: バックアップしているnamespaceをすべて取得し直す
+    * まだ何もバックアップしていない場合は、`mainsail`、`fluidd`、`mobileraker`、`maintenance`、`webcams`、`timelapse`のうち、ホストにあるものを取得する
+    * これらのうち、まだバックアップしていないものがホストにあれば案内する
+    * ホストになくなったnamespaceは取得せず、警告する(バックアップをやめる操作はまだない)
+  * `bosun backup --status`: namespaceごとに、バックアップしているかなどの状態を表示する
+* `moonraker`、`update_manager`などは、Moonrakerが内部で管理する情報で、頻繁に変わるため推奨しない
+* ホストへの書き戻し(復元)は行わない
+* `status`と`audit`の同期の状態の判定には含めない
+
+### audit
+
+`status`の内容に加えて、次のことを行う。
+
+* トラッキング中のすべてのファイルについて、HとTを厳密な方法で比べる
+* 不変条件を、`host-tracking`のすべてのコミットについて検査する
+  * マージコミット(親が2つ以上)でないこと
+  * `Host-Op`があり、既知の操作であること(`bosun`以外の経路で作られたコミットがないこと)
+  * ツリーに`config/`と`backup/`以外のファイルがないこと
+  * `Host-File`に記録したファイルがツリーにあり、`size`がblobのサイズと一致すること
+  * `Host-File`に削除(`deleted`)と記録したファイルが、ツリーにないこと
+  * `Host-DB`に記録したファイルがツリーにあること
+* 状態ごとに、解消するための手順を案内する
+* 次のいずれかがあれば、終了コードを1にする
+  * 不変条件の違反
+  * 同期済みでないファイル(トラッキングしていないファイルを除く)、名前の変更の可能性
+  * `host-tracking`の未マージのコミット
+  * 未コミットの変更は、表示するが問題としない
+
+## スナップショットの参照
+
+`host-tracking`の各コミットのツリーが、その時点で最後に取得した内容の集まり(スナップショット)になる。
+
+* `add`は指定したファイルだけを取得するので、ツリーは「その時点でホストにあったすべてのファイル」ではない
+* ローカルでの変更(`main`のコミット)は含まれない
+
+### export
+
+`bosun export`で、ある時点のツリーをディレクトリに書き出す。ホストにも作業ツリーにも書き込まない。
+
+* 時点の指定(省略時は`host-tracking`の先頭)
+  * `--at <日時>`: その日時より前で最も新しい`host-tracking`のコミット(`git rev-list -1 --before=<日時> host-tracking`)
+    * gitは解釈できない日時を黙って現在の日時として扱うことがあるので、Rubyの`Time.parse`で解釈してからISO 8601でgitに渡す
+  * `--rev <コミット>`: そのコミットと`host-tracking`の共通の祖先(`git merge-base`)
+    * `host-tracking`は一直線の履歴なので、`main`のコミットを指定すると、そのコミットの時点で取り込んでいた最新の取得の時点になる
+    * `host-tracking`のコミットを指定すると、そのコミットになる
+* 書き出す先(`-o`)
+  * 省略時は、カレントディレクトリの`export-<日時>-<コミットの短縮名>/`(`.gitignore`で除外している)
+  * すでにある場合は中止する
+* ファイルを指定すると、そのファイルだけを書き出す(Root `config`からのパスか、リポジトリ上のパス)
+
+gitで直接参照することもできる。
+
+* 履歴: `git log host-tracking --stat`
+* ある時点のファイル: `git show host-tracking~3:config/printer.cfg`
+* 名前を付けて残したい時点にはタグを打つ
+
+## 未決事項
+
+* `push`で、確認してからアップロードするまでの間にホスト側で変更が起きる場合
+  * 防げないが、印刷中でないことを確認しているので、許容する
+* ホストで削除されたファイルを、ローカルの内容からホストに戻す操作

data/docs/moonraker-api.md

@@ -0,0 +1,108 @@
+# Moonraker APIの調査結果
+
+`bosun`の実装に必要なMoonraker APIの動作を、実機で確認した結果をまとめる。
+
+* 確認日: 2026-10-11
+* 確認した環境: Moonraker v0.11.0-3-g9e676eb(API 1.5.0)、Klipper v0.13.0-787-ge2b99a915
+* プリンタの電源は入っていない状態(Klipperは`error`状態)で確認した
+
+## Root
+
+`GET /server/files/roots`
+
+| Root | ホスト側のディレクトリ | 権限 |
+| --- | --- | --- |
+| config | ~/printer_data/config | rw |
+| logs | ~/printer_data/logs | r |
+| gcodes | ~/printer_data/gcodes | rw |
+| config_examples | ~/klipper/config | r |
+| docs | ~/klipper/docs | r |
+
+## ファイルの一覧
+
+`GET /server/files/list?root=config`
+
+```json
+{"result": [
+  {"path": "printer.cfg", "modified": 1791695466.5512717, "size": 2767, "permissions": "rw"},
+  {"path": "mainsail.cfg", "modified": 1778097506.7109838, "size": 16493, "permissions": "r"}
+]}
+```
+
+* `path`はRootからの相対パス。サブディレクトリ内のファイルも含めて再帰的に返る
+* `modified`は秒単位の浮動小数点数で、マイクロ秒程度の精度がある(ホスト側の`st_mtime`)
+* `GET /server/files/directory?path=config&extended=true`でも同じ情報が得られる(`filename`、ディレクトリ単位)
+
+### permissions
+
+Moonrakerの`file_manager.py`(`get_path_info`)の実装と実機の結果から、次のように決まる。
+
+* `rw`: 通常のファイル
+* `r`: 次のいずれか
+  * 書き込みできないRoot(`logs`、`config_examples`など)のファイル
+  * **シンボリックリンク**(`mainsail.cfg`、`timelapse.cfg`)
+  * Moonrakerの予約パス(読み取り可)の下にあるファイル
+* `""`: `.git`の下にあるファイル、または読み取りも禁止された予約パスの下にあるファイル
+
+シンボリックリンクかどうかを直接示す項目はない。`bosun`では種類を判別せず、`permissions`が`rw`かどうかだけで判断する(design.mdの「対象のファイル」を参照)。
+`modified`と`size`はリンク先のファイルの値になる。
+
+## ファイルのダウンロード
+
+`GET /server/files/{root}/{path}`
+
+* 本文がファイルの内容。`Last-Modified`ヘッダが付く
+* シンボリックリンクは、リンク先の内容が返る
+* 存在しない場合は`404`
+
+## ファイルのアップロード
+
+`POST /server/files/upload`(multipart/form-data)
+
+* フィールド: `root`(省略時は`gcodes`)、`file`、`path`(任意、サブディレクトリ)、`checksum`(任意、SHA-256の16進文字列)
+* 同名のファイルがあれば**確認なしに上書きする**
+  * 新規作成と上書きのどちらでも`"action": "create_file"`が返る
+  * そのため、新しいファイルを作るときに同名のファイルがないことは、`bosun`の側で確認する必要がある
+* `checksum`が一致しない場合は`422`
+* 応答の`item`に、アップロード後の`modified`、`size`、`permissions`が含まれる
+* **シンボリックリンクと同名のファイルをアップロードすると、リンク先のファイルを書き換える**(実装で確認、実機では未実施)
+  * `bosun`は`rw`でないファイルに書き込まないので、`mainsail.cfg`などへのアップロードは起きない
+
+## ファイルの削除
+
+`DELETE /server/files/{root}/{path}`
+
+* 成功すると`"action": "delete_file"`が返る
+* 存在しない場合は`400`(`404`ではない)
+
+## ホスト側で作られるバックアップファイル
+
+| 作成元 | 名前 | 例 |
+| --- | --- | --- |
+| Klipperの`SAVE_CONFIG` | `<名前>-YYYYMMDD_HHMMSS.cfg` | `printer-20261011_141106.cfg` |
+| Moonrakerの設定の書き換え | `.<名前>.bkp` | `.moonraker.conf.bkp` |
+
+* Klipper: `klippy/configfile.py`の`time.strftime("-%Y%m%d_%H%M%S")`
+* Moonraker: `confighelper.py`の`f".{cfg.name}.bkp"`
+
+## 印刷状態
+
+`GET /printer/objects/query?print_stats`
+
+* 通常は`result.status.print_stats.state`が`standby`、`printing`、`paused`、`complete`、`cancelled`、`error`のいずれか
+* Klipperが`ready`でない場合(プリンタの電源が入っていないなど)は、`print_stats`が空のオブジェクトになる
+  * この場合、印刷は行われていない
+* Klipperの状態は`GET /printer/info`の`result.state`(`ready`、`error`、`shutdown`、`startup`)で得られる
+
+## データベース
+
+`GET /server/database/list`、`GET /server/database/item?namespace=<名前>`
+
+* namespace: `maintenance`、`moonraker`、`mainsail`、`update_manager`、`gcode_metadata`、`announcements`
+* Mainsailの設定は`mainsail`にある(`dashboard`、`general`、`gcodeViewer`、`view`など)
+* `moonraker`、`update_manager`、`gcode_metadata`、`announcements`は、Moonrakerが内部で管理する情報が中心
+
+## エラー
+
+* エラーの場合は`{"error": {"code": ..., "message": ..., "traceback": ...}}`が返る
+* `traceback`はMoonraker内部のPythonのトレースバックなので、ユーザには`code`と`message`だけを示す

data/exe/bosun

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "moonraker/bosun"
+
+exit Moonraker::Bosun::CLI.new.run(ARGV)

data/lib/moonraker/bosun/cli.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Moonraker
+  module Bosun
+    class CLI
+      COMMANDS = {
+        "roots" => Commands::Roots,
+        "ls" => Commands::Ls,
+        "get" => Commands::Get,
+        "add" => Commands::Add,
+        "pull" => Commands::Pull,
+        "status" => Commands::Status,
+        "audit" => Commands::Audit,
+        "diff" => Commands::Diff,
+        "push" => Commands::Push,
+        "forget" => Commands::Forget,
+        "rm" => Commands::Rm,
+        "backup" => Commands::Backup,
+        "export" => Commands::Export
+      }.freeze
+
+      def initialize(out: $stdout, err: $stderr, env: ENV, cwd: nil, client: nil)
+        @context = Context.new(out: out, err: err, env: env, cwd: cwd, client: client)
+      end
+
+      # メッセージの言語は、環境変数(LC_ALL、LC_MESSAGES、LANG)で決める
+      def run(argv)
+        Messages.with_locale(Messages.locale_from_env(@context.env)) { dispatch(argv) }
+      end
+
+      private
+
+      def dispatch(argv)
+        name, *args = argv
+        case name
+        when nil, "help", "-h", "--help"
+          @context.out.print usage
+          0
+        else
+          command = COMMANDS[name]
+          unless command
+            @context.err.puts "bosun: #{Messages.t(:"cli.unknown_command", name: name)}"
+            @context.err.print usage
+            return 1
+          end
+          command.new(@context).run(args)
+        end
+      rescue Error, SystemCallError => e
+        # ファイルの書き込みの失敗(Errno::EACCESなど)も、スタックトレースではなくメッセージだけを表示する
+        @context.err.puts "bosun: #{e.message}"
+        1
+      rescue Interrupt
+        @context.err.puts "bosun: #{Messages.t(:"cli.interrupted")}"
+        130
+      end
+
+      def usage
+        width = COMMANDS.keys.map(&:size).max
+        lines = COMMANDS.map { |name, command| format("  %-*s  %s", width, name, command.summary) }
+        Messages.t(:"cli.usage", commands: lines.join("\n"))
+      end
+    end
+  end
+end