# Lightsail CLI制御基盤 設計

作成日: 2026-08-10
背景: XWiki用ノード増設判断（既存Dokploy/Lightsail構成）検討中に発生。Claude Codeから直接AWS Lightsailインスタンスを操作したい要望。

---

## 1. 目的

AWS Lightsail操作（インスタンス一覧・作成削除・起動停止・スナップショット）をClaude CodeからCLI経由で実行可能にする。人間がAWSコンソール開かず、Claude Codeへの指示だけでノード管理完結させる。

---

## 2. スコープ

### 初期実装（今回）

- インスタンス一覧・状態取得
- インスタンス作成・削除
- 起動／停止／再起動
- スナップショット作成・一覧・削除

### 対象外（随時追加）

静的IPアタッチ／デタッチ、ファイアウォール（ポート開放）設定、ディスクアタッチ・追加ブロックストレージ、DNS管理、インスタンス名変更等。必要になった時点で関数・CLIコマンド追加。

---

## 3. アーキテクチャ

```
apps/app-portal/
  src/lightsailClient.js      # AWS SDKラッパー（dokployClient.js同型）
  scripts/lightsail-cli.js    # Claude Code実行用CLIエントリ
  test/lightsailClient.test.js
deploy/
  lightsail.env.example       # 新規
  lightsail.env               # 実値（gitignore済み）
```

- 依存追加: `@aws-sdk/client-lightsail`（apps/app-portal/package.json）
- `lightsailClient.js`: 関数ごとに1操作。`getConfig()`でenv読込→`LightsailClient`生成→コマンド実行。既存dokployClient.jsのパターンを踏襲
- `scripts/lightsail-cli.js`: `node scripts/lightsail-cli.js <command> [args]` 形式。結果をJSON整形出力
- 既存app-portal Webアプリとは独立実行。サーバー常時起動不要、都度node実行

---

## 4. 認証情報

専用IAMユーザー作成、`AmazonLightsailFullAccess`ポリシーをアタッチ。

- `deploy/lightsail.env.example`: `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION`（項目のみ、値は空）
- `deploy/lightsail.env`: 実値格納、gitignore済み（dokploy.envと同列運用）
- リージョン: `ap-northeast-1`（東京）固定。既存Dokploy稼働Lightsailと同一リージョン

IAMユーザー作成はAWSコンソール操作のため、ユーザー側作業。手順:

1. IAMコンソール → ユーザー作成（例: `lightsail-api-bot`）
2. アクセスキー種別「プログラムによるアクセス」
3. `AmazonLightsailFullAccess`ポリシーをアタッチ
4. アクセスキー発行、`deploy/lightsail.env`に格納

---

## 5. CLIコマンド体系

| CLIコマンド | lightsailClient.js関数 | AWS SDKコマンド |
|---|---|---|
| `list` | `listInstances()` | GetInstances |
| `status <name>` | `getInstance(name)` | GetInstance |
| `create <name> --bundle <id> --blueprint <id> --az <zone>` | `createInstance(opts)` | CreateInstances |
| `delete <name>` | `deleteInstance(name)` | DeleteInstance |
| `start <name>` | `startInstance(name)` | StartInstance |
| `stop <name>` | `stopInstance(name)` | StopInstance |
| `reboot <name>` | `rebootInstance(name)` | RebootInstance |
| `snapshot create <instance> <snapshotName>` | `createSnapshot(instance, snapshotName)` | CreateInstanceSnapshot |
| `snapshot list` | `listSnapshots()` | GetInstanceSnapshots |
| `snapshot delete <snapshotName>` | `deleteSnapshot(snapshotName)` | DeleteInstanceSnapshot |

---

## 6. 破壊的操作の扱い

`delete`系（インスタンス削除・スナップショット削除）はCLI内部に確認プロンプトを実装しない。CLIは薄く保つ。実行判断はClaude Code側（会話上でユーザーに確認取ってから実行）に委ねる。既存の「破壊的操作は事前確認」運用ルールでカバー。

---

## 7. エラーハンドリング

AWS SDKが投げる例外をそのままthrow。dokployClient.js同様、ラップしない。

---

## 8. テスト方針

`LightsailClient`インスタンスを関数の外側からDI可能にする。引数省略時は本物のSDKクライアント生成、テスト時はモッククライアントを注入し`client.send`をスタブ。dokployClient.jsの`global.fetch`モック方式と同じ発想。node:test使用（既存app-portalと統一）。

---

## 9. 未決事項

- IAMアクセスキー発行（ユーザー側作業、未実施）
- `create`コマンドのbundle/blueprint/azデフォルト値（既存Dokployノードと揃えるか、都度指定か）→ 実装時に既存ノードのスペック確認して決定