Gabu Quest
🇺🇸 English

Procler 注目 Proclerプロセスマネージャー概要

開発者向けLLMファーストプロセスマネージャー。JSON出力CLI、ローカル/Docker両対応、ヘルスプローブ付き依存順序、レプリカ、cronスケジューリング、Vue 3ダッシュボード — 320テスト。

役割: メイン開発 @ サイドプロジェクト
期間: 2025年8月
技術:
PythonFastAPIClickDockerVue 3SQLiteWebSocketsPydanticTextual

Procler

開発者向けLLMファーストプロセスマネージャー。YAMLでプロセスを定義し、JSON出力CLIまたはVue 3ダッシュボードで管理。ローカルシェルとDockerコンテナを同じコマンドで操作。全出力が構造化JSON。

なぜProcler？

docker compose up と本格的なプロセスマネージャーの間にギャップがある。Composeはコンテナには最適だがローカルシェルプロセスを管理できない。pm2はNode中心。supervisordはroot権限とXML設定が必要。いずれもAIエージェントが消費する設計になっていない。

Proclerはそのギャップを埋める。1つの設定ファイル、1つのCLI、1つのAPI — ローカルプロセスとDockerコンテナの両方に対応。全コマンドが {success, data?, error?, error_code?, suggestion?} 形式の一貫したJSONを返す。LLMエージェントは procler capabilities で全コマンドを発見し、procler config explain で現在の設定を理解し、全てをプログラム的に操作できる。

向いている場面: 開発環境のオーケストレーション、ローカルとコンテナが混在するマルチサービスプロジェクト、AI支援運用、構造化出力がテーブル整形より重要な全ての場面。

クイックスタート

pip install procler              # または: uv add procler

# プロジェクト設定を初期化
procler config init

# プロセスを定義して実行
procler define --name api --command "uvicorn main:app --reload"
procler start api
procler status api
procler logs api --tail 20

# または設定ベースのグループ
procler group start backend

設定は .procler/config.yaml — バージョン管理可能、ポータブル、人間が読める。

アーキテクチャ

YAML設定 ──→ ProcessManager ──→ ExecutionContext ──→ Shell / Docker
                     │
          ┌──────────┼──────────┐
          │          │          │
      グループ    レシピ     ヘルス
     (順序付き   (マルチ    (プローブ +
      起動)      ステップ)   依存)
          │          │          │
          └──────────┼──────────┘
                     │
              ┌──────┴──────┐
              │             │
           CLI (Click)   API (FastAPI)
           JSON stdout   REST + WebSocket
                         Vue 3ダッシュボード

ProcessManager が唯一のコーディネーター。CLIとAPIは同じコアの薄いレイヤー。ExecutionContext は抽象インターフェース — LocalContext はサブプロセスを起動し、DockerContext はDocker SDKを使用。切り替えは設定1行の変更。

機能

JSON出力CLI

全コマンドが構造化JSONを返す。stdoutのパースもテーブル出力の正規表現も不要：

# 全コマンドを発見（LLMエージェントのエントリーポイント）
procler capabilities

# Linux カーネル状態付きの構造化ステータス
procler status api
# {"success": true, "data": {"name": "api", "status": "running", "pid": 12345, ...}}

# 平文での設定説明
procler config explain

ヘルスプローブ＆依存関係

プロセスはヘルスチェックを宣言し、他プロセスの特定状態に依存できる：

processes:
  api:
    command: uvicorn main:app
    healthcheck:
      test: "curl -f http://localhost:8000/health"
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

  worker:
    command: celery worker
    depends_on:
      - name: api
        condition: healthy    # ヘルスチェック通過を待機

グループ起動は依存順序を尊重。procler group start backend はまずredisを起動し、待機し、apiを起動し、healthyを待ち、それからworkerを起動する。

グループ＆レシピ

グループは順序付きプロセス集合。レシピはマルチステップ操作：

groups:
  backend:
    processes: [redis, api, worker]
    stop_order: [worker, api, redis]

recipes:
  deploy:
    on_error: stop
    steps:
      - stop: worker
      - stop: api
      - wait: 2s
      - exec: "alembic upgrade head"
      - start: api
      - start: worker

procler recipe run deploy --dry-run    # ステップをプレビュー
procler recipe run deploy              # 実行

レプリカ＆ネームスペース

プロセスを水平スケール。ネームスペースで環境を分離：

processes:
  worker:
    command: celery worker
    replicas: 3           # worker-1, worker-2, worker-3
    namespace: staging

cronスケジューリング

cron式でプロセスをスケジュール：

processes:
  cleanup:
    command: python cleanup.py
    schedule: "0 */6 * * *"    # 6時間ごと

エクスポート＆インポート

マシン間で設定を移動、チームメイトと共有：

procler config export --output my-stack.json
procler config import my-stack.json
procler config import Procfile    # Heroku Procfileからインポート

デュアルコンテキスト: ローカル + Docker

同じコマンド、異なる実行ターゲット：

processes:
  api:
    command: python main.py
    context: local

  postgres:
    command: postgres
    context: docker
    container: my-postgres

procler start api はサブプロセスを起動。procler start postgres はDocker SDKを使用。status、logs、start、stopコマンドは両方で同一に動作する。

Linuxプロセス状態

ステータス出力に /proc/[pid]/stat からのカーネルレベル状態を含む：

{
  "linux_state": {
    "state_code": "D",
    "state_name": "disk_sleep",
    "is_killable": false
  },
  "warning": "D状態のプロセスはkillできない"
}

Webダッシュボード

Vue 3 + Naive UIダッシュボード（Cyberpunkテーマ）：

ビュー目的
ダッシュボード統計、クイックアクション、最近のアクティビティ
プロセスCRUD、ステータスインジケーター、アクション別ローディング
プロセス詳細ライブログ（検索/フィルター、ストリーム別）
グループカード型、ワンクリック全起動/停止
レシピステッププレビュー、ドライラン、実行進捗
スニペット再利用可能なコマンド管理
設定ステータス、統計、チェンジログビューアー

キーボードショートカット（? でヘルプ）、WebSocket状態表示、ステータス変更時のトースト通知、ARIAラベルによるアクセシビリティ。

TUIモード

SSH接続やヘッドレスサーバー向けのTextual製ターミナルUI：

pip install procler[tui]
procler tui

分割ペインレイアウト：左にプロセスリスト、右にライブログ。キーボード操作：矢印キーでナビ、s/x/r で起動/停止/再起動、F5 でリフレッシュ、q で終了。

リアルタイム更新

WebSocketでライブログストリーミングとステータス変更通知：

{"action": "subscribe_logs", "process_id": 1}
{"action": "subscribe_status"}

EventBusアーキテクチャ — CLI、API、TUI、ダッシュボード全てが同じイベントを受信。

正直な制限事項

  • シングルマシン — 分散プロセス管理はない。1ホスト上のプロセスを管理する。マルチマシンにはKubernetesを使う。
  • 自動再起動なし — クラッシュしたプロセスはクラッシュしたまま。ヘルスプローブは検出するが、自動再起動ポリシーは未実装。
  • SQLite状態 — ランタイム状態はSQLite。高速でシンプルだが、ホスト間で状態ファイルを共有できない。
  • Docker SDK限定 — コンテナ管理はdocker-pyを使用。PodmanやcontainerdではなくDockerのインストールが必要。
  • TUIはv1 — 起動/停止/再起動アクション、エラー状態、リフレッシュループは完全にテストされていない。監視には使えるが、操作にはまだ粗い部分がある。

はじめる

pip install procler               # または: uv add procler
pip install procler[tui]          # オプションのTUIモード

Python 3.12+ · Dockerはオプション（コンテナコンテキストのみ必要）。

uv run pytest tests/ -v           # 320テスト
procler capabilities              # 全コマンドを発見
procler config init               # プロジェクトを初期化

English: Read this project in English