@ripla/godd-mcp 1.0.6 → 1.0.7-canary.2

package/templates/notes-docs/007_guides/setup_godd_notes.md

@@ -1,36 +1,238 @@
-# GoDD Notesのはじめ方
+# GoDD Notes 構築ガイド
 
-1. GoDD をインストール
+GoDD Notes のローカル構築、インフラ作成、AWS デプロイまでの流れを記載します。
+
+> **PAT（`GITHUB_TOKEN` / `github-token`）は禁止です。** GitHub 連携には GitHub App 3変数（`GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID`）が必須です。
+
+---
+
+## 1. GoDD をインストール
+
+```shell
 npm install -g @ripla/godd-mcp
+```
+
+配布 ZIP から `godd install` する場合は [setup_godd.md](./setup_godd.md) を参照。
 
-2. プロジェクトで godd init
+## 2. プロジェクトで `godd init`
+
+```shell
 cd /path/to/your-project
 godd init
+```
+
 プロジェクトごとに実行が必要です（2人目以降のメンバーも各自実行）。
 
-3. docs/ フォルダ構造をテンプレートから生成
-Cursor
+## 3. `docs/` フォルダ構造をテンプレートから生成
+
+**Cursor:**
+
+```shell
 /godd_docs_init
+```
+
+**Claude Code:** MCP ツール `godd_docs_init` を呼び出す。
+
+---
+
+## 4. ローカル開発（任意）
+
+AWS デプロイ前にローカルで動作確認する場合:
+
+```shell
+godd notes compose
+```
+
+GitHub App 3変数は `godd notes compose`（対話 / `--auto` / `--config`）で必須です。未設定だと CLI がエラー終了します。Notes API を App なしで直接起動した場合のみモックモード（GitHub API 不使用）になります。生成される `.env` では PEM の改行を `\n` に正規化します（Compose が1行値として読めるようにするため。API 側で復元します）。
+
+---
+
+## 5. AWS 本番環境向けの事前セットアップ
+
+> **本番 AWS デプロイ時のみ必要です。** ローカル開発（`godd notes compose`）のみの場合は不要です。
+
+### 5-1. AWS アカウント構成・セキュリティ・コスト監視
+
+以下のガイドの順に整備する:
 
-4. AWS 本番環境向けの事前セットアップ（本番 AWS デプロイ時のみ）
-以下のガイドの順に、アカウント構成・セキュリティ・コスト監視を整備する:
 - [setup_aws_accounts.md](./setup_aws_accounts.md) — Organizations とアカウント構成
 - [setup_aws_guard_duty.md](./setup_aws_guard_duty.md) — GuardDuty 設定
 - [setup_aws_cost_alert.md](./setup_aws_cost_alert.md) — コスト監視（Budgets / Cost Anomaly Detection）
 
-5. クラウドインフラ構築（初回のみ）
+### 5-2. AWS CLI 認証
+
+Terraform 適用・Secrets 投入・`godd notes deploy` の前に AWS CLI で認証しておきます。
+
+```bash
+# SSO 利用例（プロファイル名は環境に合わせて変更）
+aws sso login --profile <PROFILE>
+export AWS_PROFILE=<PROFILE>   # macOS / Linux
+# PowerShell: $env:AWS_PROFILE = "<PROFILE>"
+
+# 認証確認
+aws sts get-caller-identity --profile <PROFILE> --region ap-northeast-1
+```
+
+---
+
+## 6. GitHub App 設定（必須）
+
+GoDD Notes Bot（または自前の GitHub App）を対象リポジトリにインストールします。**PAT は使用できません。**
+
+### 6-1. リポジトリアクセス権の追加（初回のみ）
+
+GitHub → Organization の Settings → Third-party Access / GitHub Apps → GoDD Notes Bot / Configure → Repository access / **Only select repositories** で対象リポジトリを追加する。
+
+App 3変数が設定済みでも、リポジトリを未追加のままだと GitHub API が 401/403 になり Notes はエラーになる（モックモードにはならない）。
+
+### 6-2. App ID / Installation ID の取得
+
+| 値 | 取得方法 |
+|---|---|
+| **App ID** | GitHub App 設定ページの **App ID**（数値） |
+| **Private Key** | App 設定 → **Generate a private key** で `.pem` をダウンロード |
+| **Installation ID** | Install App 後の URL 末尾の数字（例: `https://github.com/organizations/<org>/settings/installations/<ID>`） |
+
+詳細手順: [bot-token-setup.md](./bot-token-setup.md)
+
+---
+
+## 7. クラウドインフラ構築（初回のみ）
+
+```shell
 godd notes infra
+```
+
 対話形式で AWS リージョンや環境名を入力すると、以下が生成されます:
 
-godd-notes/ ディレクトリ（notes-api/, notes-app/）
-Terraform ファイル（VPC, ECS, RDS, S3, CloudFront 等）
-CI/CD ワークフロー
-チームで1人が実行すれば OK です。
-詳細は ./setup_infra.template.md を参照。
+- `notes-api/` / `notes-app/` ディレクトリ
+- Terraform ファイル（VPC, ECS, RDS, S3, CloudFront 等）
+- CI/CD ワークフロー
+
+チームで1人が実行すれば OK です。詳細は [setup_infra.template.md](./setup_infra.template.md) を参照。
+
+### Terraform 適用手順（概要）
+
+```bash
+bash scripts/terraform-backend-setup.sh
+
+cd terraform/godd-notes/{env}-iam
+terraform init && terraform apply
+
+cd ../{env}
+terraform init && terraform apply
+```
+
+---
+
+## 8. Secrets Manager に値を設定
+
+Terraform 適用後、`{env}` を環境名（例: `dev`）に置き換えて実行します。
+**AI エージェント経由の `put-secret-value` がブロックされる場合は、自分のターミナルで直接実行してください。**
+
+### 8-1. jwt-secret
+
+```bash
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/dev/jwt-secret \
+  --secret-string "$(openssl rand -base64 48)" \
+  --profile <PROFILE> \
+  --region ap-northeast-1
+```
+
+### 8-2. admin-credentials
+
+```bash
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/dev/admin-credentials \
+  --secret-string '{"username":"admin","password":"'$(openssl rand -base64 24)'"}' \
+  --profile <PROFILE> \
+  --region ap-northeast-1
+```
+
+管理者パスワードの確認（初回ログイン用）:
+
+```bash
+aws secretsmanager get-secret-value \
+  --secret-id godd-notes/dev/admin-credentials \
+  --profile <PROFILE> \
+  --region ap-northeast-1 \
+  --query SecretString \
+  --output text
+```
+
+### 8-3. GitHub App 3変数（必須 — PAT 禁止）
+
+```bash
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/dev/github-app-id \
+  --secret-string "<APP_ID>" \
+  --profile <PROFILE> \
+  --region ap-northeast-1
+
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/dev/github-app-private-key \
+  --secret-string file://path/to/private-key.pem \
+  --profile <PROFILE> \
+  --region ap-northeast-1
 
-6. デプロイ
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/dev/github-app-installation-id \
+  --secret-string "<INSTALLATION_ID>" \
+  --profile <PROFILE> \
+  --region ap-northeast-1
+```
+
+> ECS タスク定義は `GITHUB_TOKEN` を注入しません。既存環境の移行順序は [setup_infra.template.md](./setup_infra.template.md) の「PAT 廃止時の ECS 移行」を参照（先に deploy で TD から strip → stable → terraform apply → 手動で `github-token` 削除）。
+
+### 8-4. GitHub Secrets（CI/CD 用）
+
+```bash
+cd terraform/godd-notes/{env}
+gh secret set CLOUDFRONT_DISTRIBUTION_ID \
+  --body "$(terraform output -raw cloudfront_distribution_id)"
+```
+
+---
+
+## 9. デプロイ
+
+```shell
 godd notes deploy      # 対話形式
 godd notes deploy -y   # 確認スキップ（CI 向け）
-ローカルの godd-notes/notes-api と notes-app を AWS にデプロイします。 notes-api が GitHub の main ブランチから docs/ を読んで Notes に展開します。
+```
+
+**前提:**
+
+- `.godd-notes-infra.json` が存在し `provider` が `aws`
+- Secrets Manager に必須シークレット（jwt-secret / admin-credentials / github-app-*）が投入済み
+- **ローカルの Docker daemon（Docker Desktop 等）が起動している**（未起動だと即失敗）
+- AWS CLI 認証済み（`AWS_PROFILE` 等）
+
+`godd notes deploy` はローカルの `notes-api` / `notes-app` をビルドし、ECR / ECS / S3 / CloudFront へ反映します。notes-api が GitHub の main ブランチから `docs/` を読んで Notes に展開します。
+
+新しい `@ripla/godd-mcp` バージョンが利用可能な場合、警告が表示されることがあります。
+
+### デプロイ後の確認
+
+```bash
+godd notes status
+```
+
+`github_write_author: bot` かつ installation token refresh が OK であることを確認してください。
+
+Secrets を修正した場合は ECS を再デプロイ:
+
+```bash
+aws ecs update-service --cluster godd-notes --service notes-api --force-new-deployment \
+  --profile <PROFILE> --region ap-northeast-1
+```
+
+---
+
+## 関連ドキュメント
 
-godd notes deploy 実行時に @ripla/godd-mcp の新しいバージョンが利用可能な場合、警告が表示されます。
+- GoDD MCP セットアップ: [setup_godd.md](./setup_godd.md)
+- インフラ詳細: [setup_infra.template.md](./setup_infra.template.md)
+- Bot / GitHub App 手順: [bot-token-setup.md](./bot-token-setup.md)
+- コマンドリファレンス: [godd-commands.md](./godd-commands.md)

package/templates/notes-docs/007_guides/setup_godd_notes.md.styles.json

@@ -0,0 +1,409 @@
+{
+  "version": 1,
+  "format": "tiptap",
+  "doc": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 1
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "GoDD Notesのはじめ方"
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "1. GoDD をインストール"
+          }
+        ]
+      },
+      {
+        "type": "codeBlock",
+        "attrs": {
+          "language": "shell"
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "npm install -g @ripla/godd-mcp"
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "2. プロジェクトで godd init"
+          }
+        ]
+      },
+      {
+        "type": "codeBlock",
+        "attrs": {
+          "language": "shell"
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "cd /path/to/your-project  \ngodd init  "
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "プロジェクトごとに実行が必要です（2人目以降のメンバーも各自実行）。"
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "3. docs/ フォルダ構造をテンプレートから生成"
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "Cursor"
+          }
+        ]
+      },
+      {
+        "type": "codeBlock",
+        "attrs": {
+          "language": "shell"
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "/godd_docs_init"
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "4. AWS 本番環境向けの事前セットアップ（本番 AWS デプロイ時のみ）"
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "以下のガイドの順に、アカウント構成・セキュリティ・コスト監視を整備する:"
+          }
+        ]
+      },
+      {
+        "type": "bulletList",
+        "content": [
+          {
+            "type": "listItem",
+            "content": [
+              {
+                "type": "paragraph",
+                "attrs": {
+                  "textAlign": null
+                },
+                "content": [
+                  {
+                    "type": "text",
+                    "marks": [
+                      {
+                        "type": "link",
+                        "attrs": {
+                          "href": "./setup_aws_accounts.md",
+                          "target": "_blank",
+                          "rel": "noopener noreferrer nofollow",
+                          "class": null,
+                          "title": null
+                        }
+                      }
+                    ],
+                    "text": "setup_aws_accounts.md"
+                  },
+                  {
+                    "type": "text",
+                    "text": " — Organizations とアカウント構成"
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "type": "listItem",
+            "content": [
+              {
+                "type": "paragraph",
+                "attrs": {
+                  "textAlign": null
+                },
+                "content": [
+                  {
+                    "type": "text",
+                    "marks": [
+                      {
+                        "type": "link",
+                        "attrs": {
+                          "href": "./setup_aws_guard_duty.md",
+                          "target": "_blank",
+                          "rel": "noopener noreferrer nofollow",
+                          "class": null,
+                          "title": null
+                        }
+                      }
+                    ],
+                    "text": "setup_aws_guard_duty.md"
+                  },
+                  {
+                    "type": "text",
+                    "text": " — GuardDuty 設定"
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "type": "listItem",
+            "content": [
+              {
+                "type": "paragraph",
+                "attrs": {
+                  "textAlign": null
+                },
+                "content": [
+                  {
+                    "type": "text",
+                    "marks": [
+                      {
+                        "type": "link",
+                        "attrs": {
+                          "href": "./setup_aws_cost_alert.md",
+                          "target": "_blank",
+                          "rel": "noopener noreferrer nofollow",
+                          "class": null,
+                          "title": null
+                        }
+                      }
+                    ],
+                    "text": "setup_aws_cost_alert.md"
+                  },
+                  {
+                    "type": "text",
+                    "text": " — コスト監視（Budgets / Cost Anomaly Detection）"
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "5. GitHub App「GoDD Notes Bot」にリポジトリのアクセス権限を追加（初回のみ）"
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "  GitHub → Organization の Settings → Third-party Access / GitHub Apps → GoDD Notes Bot / Configure → Repository access / Only select repositories で対象リポジトリを追加する。"
+          },
+          {
+            "type": "hardBreak"
+          },
+          {
+            "type": "text",
+            "text": "  未追加のままだと、次の infra / deploy で GitHub App の認証が使えず、無効なトークンにフォールバックしてログイン後に API Error になる。"
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "6. クラウドインフラ構築（初回のみ）"
+          }
+        ]
+      },
+      {
+        "type": "codeBlock",
+        "attrs": {
+          "language": "shell"
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "godd notes infra  "
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "対話形式で AWS リージョンや環境名を入力すると、以下が生成されます:"
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "godd-notes/ ディレクトリ（notes-api/, notes-app/）"
+          },
+          {
+            "type": "hardBreak"
+          },
+          {
+            "type": "text",
+            "text": "Terraform ファイル（VPC, ECS, RDS, S3, CloudFront 等）"
+          },
+          {
+            "type": "hardBreak"
+          },
+          {
+            "type": "text",
+            "text": "CI/CD ワークフロー"
+          },
+          {
+            "type": "hardBreak"
+          },
+          {
+            "type": "text",
+            "text": "チームで1人が実行すれば OK です。"
+          },
+          {
+            "type": "hardBreak"
+          },
+          {
+            "type": "text",
+            "text": "詳細は ./setup_infra.template.md を参照。"
+          }
+        ]
+      },
+      {
+        "type": "heading",
+        "attrs": {
+          "textAlign": null,
+          "level": 2
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "7. デプロイ"
+          }
+        ]
+      },
+      {
+        "type": "codeBlock",
+        "attrs": {
+          "language": "shell"
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "godd notes deploy      # 対話形式  \ngodd notes deploy -y   # 確認スキップ（CI 向け）  "
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "ローカルの godd-notes/notes-api と notes-app を AWS にデプロイします。 notes-api が GitHub の main ブランチから docs/ を読んで Notes に展開します。"
+          }
+        ]
+      },
+      {
+        "type": "paragraph",
+        "attrs": {
+          "textAlign": null
+        },
+        "content": [
+          {
+            "type": "text",
+            "text": "godd notes deploy 実行時に @ripla/godd-mcp の新しいバージョンが利用可能な場合、警告が表示されます。"
+          }
+        ]
+      }
+    ]
+  },
+  "markdownSnapshot": "# GoDD Notesのはじめ方\n\n## 1. GoDD をインストール\n\n```shell\nnpm install -g @ripla/godd-mcp\n```\n\n## 2. プロジェクトで godd init\n\n```shell\ncd /path/to/your-project  \ngodd init  \n```\n\nプロジェクトごとに実行が必要です（2人目以降のメンバーも各自実行）。\n\n## 3. docs/ フォルダ構造をテンプレートから生成\n\nCursor\n\n```shell\n/godd_docs_init\n```\n\n## 4. AWS 本番環境向けの事前セットアップ（本番 AWS デプロイ時のみ）\n\n以下のガイドの順に、アカウント構成・セキュリティ・コスト監視を整備する:\n\n- [setup_aws_accounts.md](./setup_aws_accounts.md) — Organizations とアカウント構成\n- [setup_aws_guard_duty.md](./setup_aws_guard_duty.md) — GuardDuty 設定\n- [setup_aws_cost_alert.md](./setup_aws_cost_alert.md) — コスト監視（Budgets / Cost Anomaly Detection）\n\n## 5. GitHub App「GoDD Notes Bot」にリポジトリのアクセス権限を追加（初回のみ）\n\n  GitHub → Organization の Settings → Third-party Access / GitHub Apps → GoDD Notes Bot / Configure → Repository access / Only select repositories で対象リポジトリを追加する。  \n  未追加のままだと、次の infra / deploy で GitHub App の認証が使えず、無効なトークンにフォールバックしてログイン後に API Error になる。\n\n## 6. クラウドインフラ構築（初回のみ）\n\n```shell\ngodd notes infra  \n```\n\n対話形式で AWS リージョンや環境名を入力すると、以下が生成されます:\n\ngodd-notes/ ディレクトリ（notes-api/, notes-app/）  \nTerraform ファイル（VPC, ECS, RDS, S3, CloudFront 等）  \nCI/CD ワークフロー  \nチームで1人が実行すれば OK です。  \n詳細は ./setup_infra.template.md を参照。\n\n## 7. デプロイ\n\n```shell\ngodd notes deploy      # 対話形式  \ngodd notes deploy -y   # 確認スキップ（CI 向け）  \n```\n\nローカルの godd-notes/notes-api と notes-app を AWS にデプロイします。 notes-api が GitHub の main ブランチから docs/ を読んで Notes に展開します。\n\ngodd notes deploy 実行時に @ripla/godd-mcp の新しいバージョンが利用可能な場合、警告が表示されます。"
+}