cli-backend-testing

CLI + バックエンドの統合テスト

LobeHub CLI（lh）をローカル開発サーバーに接続して、バックエンドの変更を検証するための標準的なワークフローです。

使用する場面

• TRPC ルーター／サービス／モデルの変更をエンドツーエンドで検証する場合
• 新しい API フィールドやレスポンス構造の変更をテストする場合
• バックエンドの変更後に CLI コマンドの出力を検証する場合
• サーバーと CLI 間のデータフローの問題をデバッグする場合

前提条件

要件	詳細
開発サーバー	localhost:3011（Next.js）
CLI ソース	lobehub/apps/cli/
CLI 開発モード	認証情報を分離するために LOBEHUB_CLI_HOME=.lobehub-dev を使用します
認証	ローカルサーバーへのデバイスコードフローでのログイン

クイックリファレンス

CLI の開発コマンドはすべて lobehub/apps/cli/ から実行します。

# Shorthand for all commands below
CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"

ワークフロー

ステップ 1：開発サーバーが起動していることを確認する

開発サーバーがすでに起動しているか確認します。

curl -s -o /dev/null -w '%{http_code}' http://localhost:3011/ 2> /dev/null

• 接続できる場合（任意の HTTP ステータスが返される場合）：サーバーは起動しています。ステップ 2 に進みます。
• 接続できない場合：サーバーを起動します。

# From cloud repo root
pnpm run dev:next

再起動してサーバー側のコード変更を反映する場合：

lsof -ti:3011 | xargs kill
pnpm run dev:next

重要： サブモジュール内のサーバー側コード（lobehub/src/server/、lobehub/packages/）を変更した場合は、サーバーを再起動する必要があります。Next.js のホットリロードでは、サブモジュールのパッケージの変更が反映されないことがあります。

ステップ 2：CLI の認証を確認する

開発用認証情報がすでに存在するか確認します。

cat lobehub/apps/cli/.lobehub-dev/settings.json 2> /dev/null

• ファイルが存在し、"serverUrl": "http://localhost:3011" が含まれている場合：すでに認証済みです。ステップ 3 に進みます。
• ファイルがない、または別のサーバーを指している場合：ログインが必要です。ユーザーに次のコマンドを実行してもらいます。

! cd lobehub/apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3011

ログインにはブラウザーでの対話型認証（OIDC デバイスコードフロー）が必要なため、ユーザー自身が ! プレフィックスを使って実行する必要があります。ログイン後、認証情報は lobehub/apps/cli/.lobehub-dev/ に保存され、セッションをまたいで保持されます。

ステップ 3：CLI コマンドでテストする

CLI はソースから実行されるため（bun src/index.ts）、CLI 側のコード変更は再ビルドせずにすぐ反映されます。

cd lobehub/apps/cli
LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>

ステップ 4：テストデータをクリーンアップする

検証中に作成したテストデータを削除します。

LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts task delete < id > -y
LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts agent delete < id > -y

よくあるテストパターン

タスクシステム

# List tasks
$CLI task list

# Create test data with nesting
$CLI task create -n "Root Task" -i "Test instruction"
$CLI task create -n "Child Task" -i "Sub instruction" --parent T-1

# View task detail (tests getTaskDetail service)
$CLI task view T-1

# View task tree
$CLI task tree T-1

# Test lifecycle
$CLI task edit T-1 --status running
$CLI task comment T-1 -m "Test comment"

# Clean up
$CLI task delete T-1 -y

エージェントシステム

# List agents
$CLI agent list

# View agent detail
$CLI agent view <agent-id>

# Run agent (tests agent execution pipeline)
$CLI agent run <agent-id> -m "Test prompt"

ドキュメントとナレッジベース

# List documents
$CLI doc list

# Create and view
$CLI doc create -t "Test Doc" -c "Content here"
$CLI doc view <doc-id>

# Knowledge base
$CLI kb list
$CLI kb tree <kb-id>

モデルとプロバイダー

# List models and providers
$CLI model list
$CLI provider list

# Test provider connectivity
$CLI provider test <provider-id>

開発・テストサイクル

バックエンド開発の標準的なサイクルです。

1. Make code changes (service/model/router/type)
         |
2. Run unit tests (fast feedback)
   bunx vitest run --silent='passed-only' '<test-file>'
         |
3. Restart dev server (if server-side changes)
   lsof -ti:3011 | xargs kill && pnpm run dev:next
         |
4. CLI verification (end-to-end)
   LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
         |
5. Clean up test data

サーバーの再起動が必要な場合

変更箇所	再起動が必要？
lobehub/src/server/（ルーター、サービス）	はい
lobehub/packages/database/（モデル）	はい
lobehub/packages/types/	はい
lobehub/packages/prompts/	はい
lobehub/apps/cli/（CLI コード）	いいえ
src/（クラウドのオーバーライド）	はい

サーバーの再起動が不要な場合

CLI は bun src/index.ts を使ってソースから実行されるため、lobehub/apps/cli/src/ の変更は次のコマンド実行時にすぐ反映されます。

トラブルシューティング

問題	解決方法
No authentication found	login --server http://localhost:3011 を実行します
API 呼び出しで UNAUTHORIZED	トークンの有効期限が切れています。ログインを再実行します
ECONNREFUSED	開発サーバーが起動していません。pnpm run dev:next で起動します
CLI に古いデータや動作が表示される	コードの変更を反映するには、サーバーを再起動する必要があります
ポート 3011 で EADDRINUSE	サーバーはすでに起動しています。lsof -ti:3011 | xargs kill で終了します
ログインで誤ったサーバーが開く	--server http://localhost:3011 フラグを使用する必要があります（環境変数は機能しません）

認証情報の分離

モード	認証情報ディレクトリ	サーバー
開発	lobehub/apps/cli/.lobehub-dev/	localhost:3011
本番	~/.lobehub/	app.lobehub.com

2 つの環境は完全に分離されています。開発モードの認証情報は Git の対象外です。