portful

portfulv0.1.0MIT

Keep one fixed port pointed at whichever git worktree is active, and switch it without restarting the client

インストール

npm install portful

GitHub のソースコード

git worktree を使うと複数のブランチを同時に動かせますが、フロントエンドの開発サーバーのような、サーバーと通信するクライアントは 1 つのポートを使い続けます。 portful がなければ、切り替えのたびに動いているサーバーを止め、別の worktree から起動し直すことになります。 portful は、worktree ごとのバックエンドサーバーをそれぞれのポートで動かしたままにし、固定ポートに小さなリバースプロキシを置いて、そのとき有効な worktree へ転送します。 portful use で有効な worktree を変えると、次のリクエストからはその worktree に届きます。クライアントの再起動も、.env の編集も、cd も必要ありません。 portful は、portless と同じことをする部分では、portless のコマンド名と設定ファイルの構成を借りています。

特徴

リポジトリごとに 1 つの固定ポート。 portful proxy start <repo> は、リポジトリの fixedPort でプロキシをフォアグラウンドで動かします。有効な worktree をリクエストのたびに読み直し、各 HTTP レスポンスに X-Portful-Worktree ヘッダーを付けます。
worktree ごとに動き続けるサーバー。 portful serve <repo>/<worktree> は、その worktree のサーバーを、portRange の範囲から割り当てたポートで起動します。このポートは、再起動しても変わりません。どのサーバーも、環境変数 PORT、HOST、PORTFUL_URL を受け取ります。
1 つのコマンドで切り替え。 portful use <repo>/<worktree> は有効な worktree を設定します。 portful use <repo> は、peco、fzf、番号で選ぶプロンプトのいずれかで選択画面を開きます。
各ポートの行き先。 portful list は、クライアントが使うアドレス、転送先の worktree、プロキシが動いているかを、リポジトリごとに 1 行で出力します。 portful status --json は、より詳しい内容を JSON で出力します。
worktree の中でコマンドを実行。 portful exec <repo>/<worktree> <cmd...> は、その worktree のディレクトリでコマンドを実行し、フラグをそのまま渡します。
読み取り専用の診断。 portful doctor は設定、ポート、状態を報告し、問題がありそうなときは 0 以外の終了コードで終了します。

エージェントでの使い方

portful whoami で、現在のディレクトリがどのリポジトリと worktree にあるかを確かめます。 api/feature-x port 3101 (running, active) のような 1 行を出力し、--json を付けると詳細をすべて出力します。登録したリポジトリの外では、0 以外の終了コードで終了します。
portful list --json か portful status --json を読み、各固定ポートの行き先と、動いているサーバーを確かめます。
サーバーが応答しないときは portful doctor を実行します。 status が報告するのはプロセスが生きているかどうかで、接続できるかどうかではありません。 doctor は、各ポートの実際の lsof の状態を、portful が期待する状態と比べます。

はじめかた

portful には Node.js 24 以降、macOS か Linux、そして git が必要です。

npm install -g portful

マシンごとに 1 度、リポジトリを ~/.config/portful/config.json に登録します。そのうえで、チェックアウトの中の portful.json でポートを指定します。

mkdir -p ~/.config/portful
cat > ~/.config/portful/config.json <<'JSON'
{ "repos": { "api": { "path": "~/work/api" } } }
JSON

cat > ~/work/api/portful.json <<'JSON'
{
  "fixedPort": 3000,
  "portRange": [3101, 3199],
  "serve": "bundle exec rails s -p {port}"
}
JSON

worktree ごとのサーバーとプロキシを、それぞれ別のターミナルのタブで起動してから、切り替えます。

portful serve api/feature-x
portful serve api/feature-y
portful proxy start api
portful use api