メインコンテンツへスキップ

2026年4月に作ったもの

baka_mashiro約5分ProjectsPythonDev Tools

4月はとにかく手が止まらない月だった。2週間ほどで6つのプロジェクト、全部Python、それぞれ違う痒いところを掻く——でも振り返ってみると、共通のテーマが見えてくる：見えないものを見えるようにする、ということだ。環境の状態、パイプを流れるデータ、ソースコードの中に隠れたメッセージ——これらのツールはどれも、「ずっとそこにあったけど見えなかった情報」を表に出すためのものだ。

何を作ったか、なぜ作ったか、何を学んだか——順番に書いていく。

Strata — 環境の考古学

GitHub · 3コミット · Python · SQLite

こういう経験は誰でもある。何かが壊れる。「昨日は動いてたのに」。次の30分を環境変数、実行中プロセス、Dockerコンテナ、パッケージバージョンを手動で確認しながら、気づかないうちに何が変わったのかを探すことになる。

Strataはそのプロセスを丸ごと自動化する。開発環境のある時点のスナップショットを撮る——環境変数、開いているネットワークポート、実行中プロセス、設定ファイルのチェックサム、ディスク使用量、Docker状態、インストール済みパッケージバージョン——それらをローカルのSQLiteデータベースに保存する。何かが壊れたら strata diff baseline now を実行すると、何が変わったかを色分けしてレポートしてくれる。

strata diff morning afternoon

# envvars
#   + STRATA_DEMO_VAR: 'hello-world' (追加)
#   ~ PATH: '/usr/bin' -> '/usr/local/bin:/usr/bin'
# network
#   + Port 3000 がリッスン開始 (tcp)
#   - Port 8080 がリッスン停止
# packages
#   ~ node: v18.17.0 -> v20.11.0

一番気に入っているのはコレクタアーキテクチャの設計だ。各データソース（環境変数、プロセス、ネットワークなど）は collect() と is_available() を実装した自己完結型のコレクタクラスになっている。これによってStrataはグレースフルデグレードができる——Dockerが入っていなければ、Dockerコレクタは「利用不可」と報告してスキップされる。クラッシュなし、設定不要。最初は8つのコレクタで始まって、2つ目のコミットで13個まで増やした。パッケージマネージャの内訳、gitリポジトリの状態、crontab、SSHキー、クラウド設定を追加した。このアーキテクチャのおかげでそれが拍子抜けするほど簡単だった。

最新の追加はgitインテグレーションだ——Strataが各スナップショットに現在のコミットハッシュを自動的に記録するようになり、strata bisect packages python3 でパッケージバージョンがコミット履歴をどう追跡したかを確認できる。最後のコミットだけで6ファイルにわたる934行の追加があり、ほとんどがgitインテグレーションと新しいコレクタだ。この機能があると、便利なデバッグツールを「post-commitフックとして常時動かしておくもの」に変えてくれる。

BranchFS — AIエージェントのためのファイルシステム

GitHub · Python · FUSE + フォールバックモード

これはAIエージェントが探索で苦労するのを見ていて生まれたアイデアだ。エージェントがアプローチAを試みて失敗し、アプローチBを試みたいとき、どうする？変更を手動で元に戻す？Dockerコンテナを立ち上げる？git（人間のために設計されているもの）を使う？

BranchFSはAIエージェント向けに設計されたコピーオンライトのブランチファイルシステムだ。1ミリ秒以下でブランチをフォーク、変更を加え、結果を評価し、マージか破棄。ステージングエリアなし、コミットメッセージなし、インタラクティブリベースなし——エージェントがタイトなループで呼べる、速くて確定的な操作だけ。

with fs.branch_context(snap_id, name="try-something") as branch:
    (branch.workdir / "solution.py").write_text("def solve(): ...")
    result = evaluate(branch.workdir)
    if result.good:
        branch.merge()
    # マージしなかった？変更は自動的に破棄される。

技術的な課題として面白かったのは、どこでも動くようにすることだった。FUSEが使えるLinux上では、BranchFSは透過的なファイルシステムとしてマウントされる——エージェントは普通に読み書きし、コピーオンライトはカーネルレベルで起きる。でもAIエージェントはよくFUSEが使えない非特権コンテナで動く。だからFUSEなしで全く同じAPIを提供するフォールバックモードを用意した、一時ディレクトリと shutil を使って。同じインターフェース、同じセマンティクス、カーネルモジュール不要。コンテンツアドレッサブルなblobストア（SHA-256で命名されたファイル）が両方のモードで重複排除を処理し、エージェントが何十ものブランチをフォークしてもストレージオーバーヘッドを最小限に抑える。

比較の数字がすべてを語る：フォーク時間はおよそ1ms（メタデータのみ）対 git checkoutの100ms 対 Dockerコンテナ作成の1秒。エージェントが何百ものアプローチを探索するとき、この差は大きい。

Pipespy — Unixパイプラインのデバッガ

GitHub · Python · 依存関係ゼロ

Unixパイプラインは美しい、壊れるまでは。cat log | sort | grep ERROR | sort | uniq -c | sort -rn | head と書いて動くけど、どのステージがボトルネックか、どこでデータが落ちているか、3回ソートしているのに1回にできることも分からない。

Pipespyはシェルパイプラインのプロファイラ、デバッガ、静的アナライザだ。パイプライン文字列を渡すと、各ステージを実行しながらタイミング、行数、バイト数、ステージ間のサンプルデータを記録する。そしてデータフローを視覚的なレポートで表示し、ボトルネックと最大のフィルタを特定し——これが一番誇りに思うところだが——アンチパターンを検出して具体的で実行可能なリライト案を提案する。

pipespy "cat log | sort | grep ERROR | sort | grep FATAL | wc -l" --no-run

# Anti-patterns Detected:
#   [i] useless-cat (stage 1)
#       sort はファイルを直接読める。
#   [~] sort-before-grep (stage 2)
#       sort が必要以上のデータを処理している。先にgrepを移動せよ。
#   [i] grep-wc (stage 6)
#       `grep FATAL | wc -l` を `grep -c FATAL` に置き換えよ

アンチパターン検出器は8つのよくあるミス（useless cat、sort-before-grep、連続するgrepチェーン、冗長なsort、echo-piped-to-command、grep-piped-to-wc、awk-used-as-cut、フィルタなしの大きなsort）を知っており、オプティマイザは推定速度向上付きの5種類の具体的なリライトを生成する。バイト比較のための LC_ALL=C の追加、大規模データセットのための sort --parallel の使用、あるいは単純にソート前にフィルタするようにステージを並べ替えるなど。

一番トリッキーだったのはパーサだ。パイプライン文字列は | で分割するほど単純じゃない——引用符付き引数、ネストされたサブシェル、エスケープされたパイプ、環境変数プレフィックスを処理しなければならない。これを正確にやるのが作業の約30%を占めた。もう一つ触れておきたい設計判断：--no-run フラグは何も実行せずに純粋な静的解析を行うので、本番ファイルを含むパイプラインを実際に触らずにlintできる。

Machina — ステートマシンDSL

GitHub · 2コミット · Pure Python · 依存関係ゼロ

ステートマシンはどこにでも出てくる——プロトコル、UIフロー、ゲームロジック、ワークフローエンジン——でも汎用言語で定義するといつもごちゃごちゃになる。enum、switch文、遷移テーブルが絡み合って読みにくく、静的解析もできない。

Machinaはステートマシンのドメイン固有言語だ。.machina ファイルを書くと、状態、遷移、ガード、アクションをクリーンな文法で表現できる。ツールキットは実行のシミュレーション、Graphviz/Mermaidの図の生成、そして——目玉機能——合成システムの並行バグの静的解析ができる。

machine Turnstile {
    var fare = 0
    state locked {
        on coin -> unlocked { action: fare += 1 }
        on push -> locked
    }
    state unlocked {
        on push -> locked
        on coin -> unlocked { action: fare += 1 }
    }
    initial locked
}

並行合成が本当に面白いところだ。共有イベントを持つ複数のマシンを定義すると、Machinaはそれらの状態空間のデカルト積を構築し、到達可能性解析（BFS）とTarjanのSCCアルゴリズムを実行してデッドロック、到達不能な合成状態、同期競合、ライブロックリスクを見つける。これは本質的に軽量なモデルチェッカーだ——ランタイムコードが存在する前の設計時に並行バグをキャッチする。

実装はクラシックなコンパイラパイプラインだ：レキサ、再帰下降パーサ、AST、そこからアナライザ、コンポーザ、エグゼキュータ、ビジュアライザに分岐する。外部依存関係ゼロ（純粋なPython 3.11+）にしたのは、DSLツールキットのポイントは簡単にインストールできることだから。テストスイートはレキサ、パーサ、アナライザ、エグゼキュータ、コンポーザ、ビジュアライザにわたる73ケースをカバーしている。demo/ フォルダには哲学者の食事問題のデモが含まれており、デッドロック検出のデモができる——ツールが自動的にバグをキャッチするのを見るのはいつも気持ちいい。

Chimera — ポリグロットスクリプトランナー

GitHub · Python · Python、JS、Bash、SQLをサポート

これはグルースクリプトへの不満から始まった。SQLクエリがあってPythonの変換処理に渡り、それがBashのデプロイステップに渡る。今日はそれが3つの別々のファイル、壊れやすいシェルパイピング、あるいは維持したくないJupyterサーバを意味する。Chimeraなら、言語で区切られたセクションで単一の .chimera ファイルに全部まとめられる。

--- python
users = [{"name": "Alice", "score": 95}, {"name": "Bob", "score": 82}]

--- javascript
topScorers = users.filter(u => u.score >= 90);
console.log("Top:", topScorers.map(u => u.name).join(", "));

--- sql @memory
SELECT name, score FROM users WHERE score > 90

--- python
for row in result:
    print(f"{row['name']}: {row['score']}")

マジックはデータブリッジングにある。あるセクションで定義された変数は、ネイティブ型として次のセクションに自動的に流れ込む。PythonリストはJavaScript配列になる。dictのリストはSQLiteテーブルになる。Bashは大文字の環境変数と chimera_export ヘルパーを受け取って、データを送り返せる。各言語エグゼキュータはユーザのコードをハーネスでラップし、実行前にコンテキストを注入して実行後に新しい変数をキャプチャする——Pythonなら実行前に globals().update(context) して、実行後に dir() を調べる。

アーキテクチャには95のテストがあり、パーサ、コンテキストシステム、個別エグゼキュータ、ランナー、フル統合テストをカバーしている。エラーハンドリングには特に気を使った——JavaScriptセクションが失敗したとき、エラーメッセージにはラッパーの行番号ではなく、セクション番号と元の行番号が含まれる。細かいことだけど、ポリグロットスクリプトのデバッグを実際に可能にする。

Murmur — Pythonソースコードのステガノグラフィ

GitHub · Python · 依存関係ゼロ

これが変わり種だ。MurmurはPythonのシンタックスが同等の選択肢を提供するところを利用して、Pythonソースコードの中に秘密のメッセージを隠す。シングルクォートかダブルクォートか？x += 1 か x = x + 1 か？return x か return (x) か？x is None か x == None か？各選択ポイントが1ビットをエンコードする。変更されたファイルは構文的に正しく、機能的に同一で、隠されたペイロードを持つ。

murmur analyze mycode.py
# Total capacity: 292 bits (31 usable bytes)
#   string_quote: 153 sites
#   return_paren: 28 sites
#   trailing_semicolon: 93 sites

murmur encode mycode.py "secret message" -o encoded.py
python encoded.py  # 元と同一の出力
murmur decode encoded.py  # "secret message"

6つのエンコードチャンネル（文字列クォート、拡張代入、returnの括弧化、比較順、None-checkスタイル、末尾セミコロン）はそれぞれ利用可能なサイトをスキャンして独立してフリップできる。鍵ベースのFisher-Yatesシャッフルがどのサイトがどのビットを持つかを決めるので、鍵なしではサイト順序をブルートフォースしなければならない。

一番面白いエンジニアリングの問題はチャンネル間干渉だった。x += 1 を x = x + 1 に変えると、その行の後のすべての列位置がシフトし、同じ行の他のチャンネルのサイトを無効化してしまう。解決策は反復エンコーダだ：全ビットをエンコードし、再スキャンし、ミスマッチをチェックし、収束するまで再適用する。実際には1〜2パスで済む。8ビットのチェックサム（SHA-256の切り詰め）が間違った鍵や破損したキャリアを検出する。

ユースケースは限られているが確かに存在する：著作権証明のためのコード透かし、コードベースのどのコピーが漏れたかを追跡すること、改ざん検知（キャリアを変更するとメッセージが破壊される）。暗号的に堅牢なステガノグラフィではない——スタイル選択の統計的解析で検出できる——でも、スタイルは情報であるという原則の本当に楽しいアプリケーションだ。

共通するもの

この6つのプロジェクトを一緒に見ると、「開発者ツール」を超える共通の糸が見える。どれもが隠れた構造を明示的にすることについてだ。

Strataは開発環境の見えない変化を可視化する。BranchFSはAIエージェントが内部でやっている分岐探索を、具体的で検査可能なファイルシステム操作にする。Pipespyはパイプラインの内部で通常は不透明なデータフローとパフォーマンス特性を明らかにする。Machinaは通常コードの中で暗黙的なステートマシンのロジックを取り出し、ファーストクラスで解析可能な表現を与える。Chimeraは言語間のデータの受け渡し——通常はシリアライゼーションのグルーに埋もれている——を自動化して透明にする。そしてMurmurは逆方向に進み、存在しないように見えるところに意図的に構造を隠す。

また全部純粋なPython、依存関係ゼロまたは最小限、5分で使い始められるように設計されている。最近、pip install 一発で使えるツールを作ることに凝っている。Docker不要、サーバ不要、設定ファイル不要。一つのことをうまくやるCLIだけ。

4月はまだ終わっていないけど、この6つは一つのまとまりを感じる。それぞれが何かを教えてくれた——コレクタアーキテクチャ、FUSEファイルシステムの内部構造、パイプライン解析のエッジケース、積状態空間解析、プロセス間の変数シリアライゼーション、そしてPythonの構文的曖昧性の意外な深さ。悪くない月だ。