headlenss-g2-plugin

開発中の G2 プラグインを headlenss から開けるようにする

headlenss (app 2.5.0 以降) は、tmux セッションのフォルダに置かれた宣言ファイルを読み、 そのセッションの下に G2 プラグインをぶら下げて表示する。グラスの一覧からタップすると WebView ごとそのプラグインへ遷移する。

  myproject [Claude]       さっきの続きだけど…
▶   └ MyPlugin                       ← ここでタップすると開く

QR の再スキャンなしに開発中プラグインを開けるのが目的。

このスキルは環境非依存。 例に出てくるホスト名・ポート・パスはすべて置き換える前提で 書いてある。まず「0. 環境を調べる」で自分の環境の値を確定させること。

絶対に守ること

1. ポート番号から「自分のサーバ」と判断しない。 中身を取得して自分のものか確かめる (手順 3)。複数プロジェクトが同じポートを直書きしている事故が実際に起きている

2. 他プラグインの環境を壊さない。 ポートが埋まっていたら自分が別のポートへ移る。 相手の dev server を落とす・設定を書き換える・共有ファイルの他人の行をいじる、はしない

3. 自分のプラグインの画面が出るのを見るまで「できた」と言わない (手順 4-(3))

4. プロセスを kill しない。 共有プロキシを kill / pkill / killall / PID 指定の シグナルで止めない。ps や ss で得た親 PID・祖先 PID は診断情報であって停止対象では ない。子プロセスを止めたいからといって、親や祖先を kill しない

   以下は絶対に停止対象に含めない:

   • /usr/lib/systemd/systemd --user (ユーザーマネージャ本体)
   • cgroup が user@<uid>.service/init.scope のプロセス
   • tmux サーバー
   • headlenss.service
   • 自分が起動していない共有サービス全般

   正常手順 (後述の systemctl --user restart) が失敗したら、代替の kill 手段を 発明せず、作業を止めてユーザーに確認する。

   実際に起きた事故: 「設定を変えたらプロキシを再起動する」という手順に従い、稼働中 プロキシの PID を ps の祖先チェーンで遡って node → sh → npm → systemd --user と まとめて kill した。末端が PID 1133 = systemd ユーザーマネージャ本体だったため、 ユーザーセッション全体 (headlenss、tmux 全 27 セッション) が落ちた。

0. 環境を調べる (最初に必ずやる)

以下を確定させてから先へ進む。推測しない。

headlenss サーバのアドレス

グラス側アプリの設定に入っている URL。サーバ側からは systemd / プロセスで確認できる。

systemctl --user status headlenss 2>/dev/null | head -3   # 常駐しているか
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/api/health

外から見えるアドレスは公開方法による。tailscale なら:

tailscale serve status
tailscale status --json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['Self']['DNSName'].rstrip('.'), d['Self']['TailscaleIPs'][0])"

リポジトリの場所

# headlenss (サーバ + G2 アプリ)
#   [email protected]:takashicompany/headlenss.git
# Plugin Loader (シム注入プロキシ。戻る動作に使う)
#   [email protected]:takashicompany-org/plugin-loader.git