diff --git a/.claude/commands/setup-new-repo.md b/.claude/commands/setup-new-repo.md index 1a045e66..fbcd8e77 100644 --- a/.claude/commands/setup-new-repo.md +++ b/.claude/commands/setup-new-repo.md @@ -15,11 +15,13 @@ argument-hint: ' [--minimal] [--no-devcontainer] [--no-codespaces] [ 1. **Git初期化** - リポジトリの初期化 2. **DevContainer** - `.devcontainer/` と `.vscode/` 設定（Codespaces 対応含む） 3. **Git設定** - commitlint, `.gitignore` -4. **GitHub Actions** - CI workflow, Claude Code workflow, Issue/PRテンプレート -5. **開発ツール** - ESLint, Prettier, Jest, Husky -6. **ドキュメント** - README.md, CLAUDE.md, SECURITY.md -7. **Codespaces シークレット** - リポジトリへのシークレット紐付け -8. **ブランチ保護 & リポジトリ設定** - main ブランチ保護、セキュリティ設定 +4. **GitHub Actions** - CI, Claude Code, Security, Code Review workflow, Issue/PRテンプレート +5. **Claude Code Hooks** - `.claude/hooks/` と `.claude/settings.json` +6. **開発ツール** - ESLint, Prettier, Jest, Husky, lint-staged, `.node-version` +7. **ドキュメント** - README.md, CLAUDE.md, SECURITY.md +8. **依存関係インストール & Husky フック** - npm install, commit-msg / pre-commit / pre-push +9. **Codespaces シークレット** - リポジトリへのシークレット紐付け +10. **ブランチ保護 & リポジトリ設定** - main ブランチ保護、セキュリティ設定 ## Step 1: Parse Arguments @@ -211,6 +213,8 @@ Thumbs.db mkdir -p TARGET_DIR/.github/workflows cp CONFIG_REPO/.github/workflows/ci.yml TARGET_DIR/.github/workflows/ cp CONFIG_REPO/.github/workflows/claude.yml TARGET_DIR/.github/workflows/ +cp CONFIG_REPO/.github/workflows/security.yml TARGET_DIR/.github/workflows/ +cp CONFIG_REPO/.github/workflows/claude-code-review.yml TARGET_DIR/.github/workflows/ mkdir -p TARGET_DIR/.github/ISSUE_TEMPLATE cp -r CONFIG_REPO/.github/ISSUE_TEMPLATE/* TARGET_DIR/.github/ISSUE_TEMPLATE/ @@ -225,9 +229,75 @@ CI workflow と合わせて必ずコピーする。 **前提**: リポジトリの Secrets に `CLAUDE_CODE_OAUTH_TOKEN` の設定が必要。 -## Step 8: Setup Development Tools +### 7.2 Security workflow -### 8.1 package.json 作成 +`security.yml` はセキュリティ関連の自動チェック（依存脆弱性スキャン等）を実行する workflow。 + +**前提**: リポジトリの Secrets に `SLACK_CI_CHANNEL_ID`, `SLACK_BOT_TOKEN` の設定が必要。 + +### 7.3 Claude Code Review workflow + +`claude-code-review.yml` は PR に対して Claude による自動コードレビューを実行する workflow。 + +## Step 8: Setup Claude Code Hooks + +Claude Code の品質ゲートフックをセットアップする。 + +### 8.1 hooks ディレクトリ作成とファイルコピー + +```bash +mkdir -p TARGET_DIR/.claude/hooks +cp CONFIG_REPO/.claude/hooks/block_git_no_verify.py TARGET_DIR/.claude/hooks/ +cp CONFIG_REPO/.claude/hooks/pre_git_quality_gates.py TARGET_DIR/.claude/hooks/ +cp CONFIG_REPO/.claude/hooks/post_git_push_ci.py TARGET_DIR/.claude/hooks/ +``` + +### 8.2 `.claude/settings.json` 作成 + +hooks セクションのみ含める。permissions セクションはプロジェクト固有のため含めない（ユーザーが後から設定）。 + +```json +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash -c 'cd \"$(git rev-parse --show-toplevel 2>/dev/null || echo .)\" && python3 .claude/hooks/block_git_no_verify.py'" + } + ] + }, + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash -c 'cd \"$(git rev-parse --show-toplevel 2>/dev/null || echo .)\" && python3 .claude/hooks/pre_git_quality_gates.py'" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash -c 'cd \"$(git rev-parse --show-toplevel 2>/dev/null || echo .)\" && python3 .claude/hooks/post_git_push_ci.py'" + } + ] + } + ] + } +} +``` + +## Step 9: Setup Development Tools + +### 9.1 package.json 作成 ```json { @@ -242,6 +312,7 @@ CI workflow と合わせて必ずコピーする。 "test": "jest", "test:watch": "jest --watch", "test:coverage": "jest --coverage", + "typecheck": "tsc --noEmit", "prepare": "husky" }, "devDependencies": { @@ -250,12 +321,13 @@ CI workflow と合わせて必ずコピーする。 "eslint": "^9.0.0", "husky": "^9.0.0", "jest": "^29.0.0", + "lint-staged": "^15.0.0", "prettier": "^3.0.0" } } ``` -### 8.2 設定ファイルをコピー +### 9.2 設定ファイルをコピー ```bash cp CONFIG_REPO/eslint.config.mjs TARGET_DIR/ @@ -263,9 +335,33 @@ cp CONFIG_REPO/.prettierrc TARGET_DIR/ cp CONFIG_REPO/jest.config.js TARGET_DIR/ ``` -## Step 9: Create Documentation +### 9.3 ESLint 複雑度ルールを強化 + +コピーした `eslint.config.mjs` の `files: ['**/*.{js,jsx}']` ブロック内の `rules` で、`complexity` と `max-depth` を `warn` から `error` に変更する。 + +Edit を使用して以下のルールを変更： + +- `complexity: ['warn', { max: 15 }]` → `complexity: ['error', 10]` +- `'max-depth': ['warn', 4]` → `'max-depth': ['error', 4]` + +### 9.4 `.node-version` ファイル作成 + +``` +22 +``` + +### 9.5 `lint-staged.config.js` 作成 + +```js +module.exports = { + '*.{ts,tsx,js,jsx}': ['eslint --fix', 'prettier --write'], + '*.{json,md,yml,yaml,css}': ['prettier --write'], +}; +``` -### 9.1 README.md +## Step 10: Create Documentation + +### 10.1 README.md プロジェクト名を含むREADMEを作成： @@ -313,17 +409,17 @@ Please read [CLAUDE.md](./CLAUDE.md) for development guidelines. This project is licensed under the {LICENSE} License. ``` -### 9.2 CLAUDE.md +### 10.2 CLAUDE.md ```bash cp CONFIG_REPO/.claude/CLAUDE.md TARGET_DIR/ ``` -### 9.3 SECURITY.md +### 10.3 SECURITY.md セキュリティポリシーを作成。 -## Step 10: Install Dependencies (unless --no-install) +## Step 11: Install Dependencies & Setup Husky Hooks (unless --no-install) ```bash cd TARGET_DIR @@ -331,18 +427,28 @@ npm install npx husky init ``` -## Step 11: Add to Codespaces Secrets (Default) +### 11.1 Husky フック作成 + +Husky v9+ では `.husky.sh` ヘッダは不要。フックは plain shell script として動作する。 + +```bash +echo 'npx commitlint --edit "$1"' > .husky/commit-msg +echo 'npx lint-staged' > .husky/pre-commit +echo 'npm run typecheck && npm run lint && npm run test' > .husky/pre-push +``` + +## Step 12: Add to Codespaces Secrets (Default) Codespaces でリポジトリを使用できるように、シークレットの紐付けをデフォルトで実行する。 `--no-codespaces` オプションが指定された場合のみスキップ。 -### 11.1: Check if codespaces-secrets.sh is available +### 12.1: Check if codespaces-secrets.sh is available ```bash test -f CONFIG_REPO/script/codespaces-secrets.sh && echo "available" || echo "not_available" ``` -### 11.2: Add repository to Codespaces secrets +### 12.2: Add repository to Codespaces secrets ```bash # リポジトリをシークレット管理対象に追加 @@ -352,7 +458,7 @@ CONFIG_REPO/script/codespaces-secrets.sh repos add {owner}/{repo-name} CONFIG_REPO/script/codespaces-secrets.sh sync ``` -### 11.3: Verify setup +### 12.3: Verify setup ```bash # 紐付け状態を確認 @@ -361,12 +467,12 @@ CONFIG_REPO/script/codespaces-secrets.sh list シークレットスクリプトが利用できない場合は、手動設定のガイドを表示する。 -## Step 12: Branch Protection & Repository Settings (unless --no-protection) +## Step 13: Branch Protection & Repository Settings (unless --no-protection) リモートリポジトリが存在する場合、ブランチ保護とリポジトリ設定を自動適用する。 リモートが設定されていない場合はスキップし、Summary の Next Steps に手動設定のガイドを表示する。 -### 12.1: リモートリポジトリの存在確認 +### 13.1: リモートリポジトリの存在確認 ```bash # リモートが設定されているか確認 @@ -375,7 +481,7 @@ git -C TARGET_DIR remote get-url origin 2>/dev/null リモートが存在しない場合はこのステップ全体をスキップする。 -### 12.2: リポジトリ設定を更新 +### 13.2: リポジトリ設定を更新 ```bash gh api repos/{owner}/{repo} --method PATCH --input - <<'EOF' @@ -401,7 +507,7 @@ EOF - Secret scanning: 有効 - Push protection: 有効 -### 12.3: main ブランチ保護ルールを設定 +### 13.3: main ブランチ保護ルールを設定 ```bash gh api repos/{owner}/{repo}/branches/main/protection --method PUT --input - <<'EOF' @@ -433,7 +539,7 @@ EOF - ブランチ更新必須（strict） - Force push / ブランチ削除: 禁止 -### 12.4: 設定結果を確認 +### 13.4: 設定結果を確認 ```bash gh api repos/{owner}/{repo}/branches/main/protection --jq '{ @@ -443,7 +549,7 @@ gh api repos/{owner}/{repo}/branches/main/protection --jq '{ }' ``` -## Step 13: Generate Summary +## Step 14: Generate Summary ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -457,14 +563,23 @@ Files Created: ✅ .vscode/ ✅ .github/workflows/ci.yml ✅ .github/workflows/claude.yml +✅ .github/workflows/security.yml +✅ .github/workflows/claude-code-review.yml ✅ .github/ISSUE_TEMPLATE/ ✅ .github/PULL_REQUEST_TEMPLATE.md +✅ .claude/hooks/ (3 ファイル) +✅ .claude/settings.json ✅ package.json ✅ eslint.config.mjs ✅ .prettierrc ✅ jest.config.js ✅ commitlint.config.js +✅ .node-version +✅ lint-staged.config.js ✅ .gitignore +✅ .husky/commit-msg +✅ .husky/pre-commit +✅ .husky/pre-push ✅ README.md ✅ CLAUDE.md ✅ SECURITY.md @@ -482,6 +597,8 @@ Next Steps: 5. gh repo create (if not yet created) 6. git push -u origin main 7. Set CLAUDE_CODE_OAUTH_TOKEN in repository secrets +8. Set SLACK_CI_CHANNEL_ID in repository secrets (security.yml 用) +9. Set SLACK_BOT_TOKEN in repository secrets (security.yml 用) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` diff --git a/docs/setup/README.md b/docs/setup/README.md new file mode 100644 index 00000000..04e60cd7 --- /dev/null +++ b/docs/setup/README.md @@ -0,0 +1,392 @@ +# セットアップガイド + +プロジェクト種別ごとのセットアップ手順を提供する。 +[CLAUDE.md](../../CLAUDE.md) の品質基準に基づく。 + +## 共通品質ゲート（全プロジェクト必須） + +| 品質ゲート | 基準 | +| ------------ | --------------------------------------------------- | +| Unit テスト | 全プロジェクトで導入必須 | +| カバレッジ | 70%+ (lines / branches / functions / statements) | +| Lint | Error=Fail、`--max-warnings 0` | +| Format 検証 | CI で `format:check` を実行、Auto-fix 無効時は Fail | +| CI/CD | Lint → Test → Build → SCA → Deploy | +| Git hooks | husky + commitlint + lint-staged（または lefthook） | +| CLAUDE.md | 技術スタック・テスト戦略・デプロイ先を記載 | +| SAST | Critical 検知で Fail | +| DevContainer | `ghcr.io/keito4/config-base:latest` ベース | + +## プロジェクト別ガイド + +| ガイド | 対応種別 | +| ---------------------------------------------------- | --------------------- | +| [spa-react-vite.md](./spa-react-vite.md) | SPA (React + Vite) | +| [npm-library-cli.md](./npm-library-cli.md) | npm ライブラリ (CLI) | +| [web-app-nextjs.md](./web-app-nextjs.md) | Web アプリ (Next.js) | +| [mobile-flutter.md](./mobile-flutter.md) | モバイル (Flutter) | +| [mobile-android.md](./mobile-android.md) | モバイル (Android) | +| [desktop-extension-ts.md](./desktop-extension-ts.md) | デスクトップ拡張 (TS) | + +--- + +## 共通パターン（プロジェクト非依存） + +以下はすべてのプロジェクトに適用すべき共通パターン。 + +### husky + commitlint + lint-staged + +3 フックパターンを標準とする。 + +```bash +npm install -D husky @commitlint/cli @commitlint/config-conventional lint-staged +npx husky init +``` + +**commit-msg** (`commitlint`): + +```bash +echo 'npx commitlint --edit "$1"' > .husky/commit-msg +``` + +**pre-commit** (`lint-staged`): + +```bash +echo 'npx lint-staged' > .husky/pre-commit +``` + +**pre-push** (typecheck + lint + test): + +```bash +echo 'npm run typecheck && npm run lint && npm run test' > .husky/pre-push +``` + +> Node.js 非依存のプロジェクト（Flutter / Android）は [lefthook](https://github.com/evilmartians/lefthook) を使用する。 + +**commitlint.config.js**: + +```js +module.exports = { + extends: ['@commitlint/config-conventional'], + rules: { + 'body-max-line-length': [2, 'always', 120], + // 日本語コミットメッセージを許可 + 'subject-case': [0], + }, +}; +``` + +### CI/CD パイプライン + +#### 最小構成 + +``` +変更検出 → Lint + Format → Test (coverage) → Build → Quality Gate +``` + +#### paths-filter による条件実行 + +不要なジョブの実行を回避し CI を高速化する。 + +```yaml +jobs: + changes: + runs-on: ubuntu-latest + outputs: + code: ${{ steps.filter.outputs.code }} + scripts: ${{ steps.filter.outputs.scripts }} + steps: + - uses: actions/checkout@v4 + - uses: dorny/paths-filter@v3 + id: filter + with: + filters: | + code: + - '**.ts' + - '**.tsx' + - 'src/**' + scripts: + - '**.sh' + - 'script/**' +``` + +#### concurrency（重複実行防止） + +```yaml +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true +``` + +#### Quality Gate 集約ジョブ + +Branch Protection の Required Status Check に **このジョブだけ** を指定する。個別ジョブの追加・削除時にルール変更が不要になる。 + +```yaml +quality-gate: + runs-on: ubuntu-latest + needs: [lint, test, build] + if: always() + steps: + - name: Verify all checks passed + run: | + for result in "$LINT" "$TEST" "$BUILD"; do + if [[ "$result" != "success" && "$result" != "skipped" ]]; then + echo "::error::Quality gate failed" + exit 1 + fi + done + env: + LINT: ${{ needs.lint.result }} + TEST: ${{ needs.test.result }} + BUILD: ${{ needs.build.result }} +``` + +#### PR サイズラベリング + +PR の diff 行数・ファイル数に応じて `size/XS` 〜 `size/XL` ラベルを自動付与する。XL（1000 行超 or 30 ファイル超）は警告コメントを投稿する。 + +```yaml +pr-size-check: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/github-script@v7 + with: + script: | + const { additions, deletions, changed_files } = context.payload.pull_request; + const total = additions + deletions; + const sizes = [ + { label: 'size/XS', maxLines: 50, maxFiles: 3 }, + { label: 'size/S', maxLines: 200, maxFiles: 10 }, + { label: 'size/M', maxLines: 500, maxFiles: 15 }, + { label: 'size/L', maxLines: 1000, maxFiles: 30 }, + ]; + let sizeLabel = 'size/XL'; + for (const s of sizes) { + if (total <= s.maxLines && changed_files <= s.maxFiles) { + sizeLabel = s.label; + break; + } + } + // ラベル付与（省略） +``` + +#### Slack 失敗通知 + +main ブランチの CI 失敗時に Slack へ通知する。 + +```yaml +notify-failure: + needs: [quality-gate] + if: failure() && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + steps: + - uses: slackapi/slack-github-action@v2 + with: + channel-id: ${{ vars.SLACK_CI_CHANNEL_ID }} + payload-file-path: '.github/slack-ci-failure.json' + env: + SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} +``` + +#### actionlint（ワークフロー構文検証） + +```yaml +actionlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: reviewdog/action-actionlint@v1 + with: + reporter: github-pr-review + fail_on_error: true +``` + +### セキュリティワークフロー（security.yml） + +4 ジョブ構成を標準とする。 + +| ジョブ | 内容 | トリガー | +| ------------------- | ------------------------------ | --------- | +| `gitleaks` | シークレット検出 | push + PR | +| `dependency-review` | 依存パッケージの脆弱性レビュー | PR のみ | +| `npm-audit` | npm 脆弱性スキャン | push + PR | +| `license-check` | 禁止ライセンス検出 | push + PR | + +**ポイント**: + +- `dependency-review`: `fail-on-severity: critical`、`deny-licenses: GPL-3.0, AGPL-3.0` +- `license-check`: `--failOn "GPL-3.0;AGPL-3.0;GPL-2.0;AGPL-1.0"` +- `schedule: cron: '0 5 * * *'` で日次実行を追加 + +### Claude Code Hooks + +Claude Code の操作前後に品質チェックを自動実行する仕組み。`.claude/hooks/` にスクリプトを配置し、`.claude/settings.json` で設定する。 + +#### 推奨 Hooks 構成 + +| Hook | タイミング | 用途 | +| -------------------------- | ----------- | ------------------------------------------ | +| `block_git_no_verify.py` | PreToolUse | `--no-verify` / `HUSKY=0` の使用をブロック | +| `pre_git_quality_gates.py` | PreToolUse | commit/push 前に品質チェック一括実行 | +| `post_git_push_ci.py` | PostToolUse | push 後に CI 状態を自動監視 | + +#### settings.json の設定例 + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [".claude/hooks/block_git_no_verify.py", ".claude/hooks/pre_git_quality_gates.py"] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [".claude/hooks/post_git_push_ci.py"] + } + ] + } +} +``` + +#### Quality Gates の実行内容 + +`pre_git_quality_gates.py` は `git commit` / `git push` を検出し、以下を順次実行する: + +1. Format Check (`npm run format:check`) +2. Lint (`npm run lint`) +3. Test (`npm run test`) +4. ShellCheck (`npm run shellcheck`) +5. Security Credential Scan +6. Code Complexity Check + +> ツールが未インストールの場合は自動スキップし、検出された問題のみブロックする。 + +### Claude Code ワークフロー + +2 つのワークフローを標準で導入する。 + +| ワークフロー | トリガー | 用途 | +| ------------------------ | -------------------- | ------------------------- | +| `claude.yml` | `@claude` メンション | Issue/PR での AI アシスト | +| `claude-code-review.yml` | PR 作成・更新 | 自動コードレビュー | + +> config リポジトリのワークフローをテンプレートとして使用する。 + +### DevContainer + +#### ベースイメージ + +```json +{ + "image": "ghcr.io/keito4/config-base:latest" +} +``` + +> `:latest` タグで常に最新の安定版を使用する。`/config-base-sync-check` でバージョンを確認可能。 + +#### 共通 mounts + +```json +{ + "mounts": [ + "source=${localEnv:HOME}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,readonly", + "source=${localEnv:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind" + ] +} +``` + +#### プロジェクト固有 Features の判断基準 + +ベースイメージに含まれるもの（git, node, pnpm, gh, jq-likes, supabase-cli）は **Features として追加しない**。プロジェクト固有のものだけ追加する: + +| プロジェクト種別 | 追加 Features 例 | +| ---------------- | ---------------------------- | +| Next.js | docker-in-docker, playwright | +| Flutter | flutter, java(17) | +| Android | java(17) + Gradle | +| Raycast 拡張 | docker-in-docker | + +### リリース管理（semantic-release） + +Node.js プロジェクトは **semantic-release** を標準とする。 + +```json +{ + "branches": ["main"], + "plugins": [ + ["@semantic-release/commit-analyzer", { "preset": "conventionalcommits" }], + ["@semantic-release/release-notes-generator", { "preset": "conventionalcommits" }], + "@semantic-release/changelog", + "@semantic-release/npm", + "@semantic-release/github", + ["@semantic-release/git", { "assets": ["CHANGELOG.md", "package.json", "package-lock.json"] }] + ] +} +``` + +> Flutter / Android は日付ベースバージョニング（`v{YYYY.MM.DD}-{short-sha}`）を使用する場合がある。 + +### ファイルサイズ制約 + +全プロジェクトに以下の制約を適用する: + +| 制約 | 閾値 | 検出方法 | +| ---------------------------- | ---------- | -------------------------- | +| 1 ファイルの行数 | 500 行以下 | Code Complexity Check | +| 関数の Cyclomatic Complexity | 10 以下 | ESLint `complexity` ルール | +| 認知的複雑度 | 15 以下 | ESLint `max-depth` ルール | +| ネストの深さ | 4 以下 | ESLint `max-depth` ルール | + +**ESLint ルール例**: + +```json +{ + "complexity": ["error", 10], + "max-lines": ["warn", { "max": 500, "skipBlankLines": true, "skipComments": true }], + "max-depth": ["error", 4] +} +``` + +> Biome を使用するプロジェクトでは `noExcessiveCognitiveComplexity` ルールで同等の制約を実現する。 + +### ライブラリ自動更新 + +依存パッケージを定期的に最新化する仕組み。 + +```yaml +name: Update Libraries +on: + schedule: + - cron: '0 0 * * 1' # 毎週月曜 + workflow_dispatch: +jobs: + update: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: npm update + - uses: peter-evans/create-pull-request@v7 + with: + title: 'chore(deps): update dependencies' + branch: chore/update-dependencies +``` + +--- + +## 共通コマンド + +| コマンド | 用途 | +| --------------------------- | ----------------------------------------------- | +| `/setup-husky` | husky + lint-staged + commitlint の最小構成導入 | +| `/setup-ci` | CI/CD ワークフローの雛形作成 | +| `/setup-new-repo` | 新規リポジトリの初期セットアップ一式 | +| `/config-base-sync-update` | DevContainer ベースイメージを最新版に更新 | +| `/config-base-sync-check` | 現在のベースイメージバージョンを確認 | +| `/security-credential-scan` | 認証情報の漏洩スキャン | +| `/code-complexity-check` | コード複雑度チェック | +| `/dependency-health-check` | 依存パッケージの健全性チェック | diff --git a/docs/setup/desktop-extension-ts.md b/docs/setup/desktop-extension-ts.md new file mode 100644 index 00000000..2eb15c35 --- /dev/null +++ b/docs/setup/desktop-extension-ts.md @@ -0,0 +1,92 @@ +# デスクトップ拡張 (TS) セットアップガイド + +## テスト環境（Vitest + Raycast API モック） + +```ts +// extensions//vitest.config.ts +import { defineConfig } from 'vitest/config'; +import path from 'path'; + +export default defineConfig({ + test: { + globals: true, + include: ['src/**/*.test.ts'], + }, + resolve: { + alias: { + // Raycast API をモック化 + '@raycast/api': path.resolve(__dirname, 'src/__mocks__/raycast-api.ts'), + }, + }, +}); +``` + +> **Raycast API モック**: `@raycast/api` を `resolve.alias` でモックファイルに差し替えるパターンが有効。 + +**各拡張への展開手順**: + +1. 各拡張の `package.json` に `vitest` + `@vitest/coverage-v8` を追加 +2. `vitest.config.ts` を作成（上記パターンをベースに） +3. `src/__mocks__/raycast-api.ts` を作成 +4. ビジネスロジックを純粋関数に分離してテスト対象に + +## CI テストステップ + +```yaml +- name: Run tests + run: | + for dir in extensions/*/; do + if [ -f "$dir/vitest.config.ts" ]; then + name=$(basename "$dir") + echo "Testing $name" + pnpm --filter "$name" test + fi + done +``` + +## CI lint strict 化 + +`continue-on-error: true` を削除し、`@raycast/eslint-config` との互換性問題は個別ルール override で解消する。 + +**段階的アプローチ**: + +1. ローカルで `pnpm lint` を実行し、現在のエラーを特定 +2. `@raycast/eslint-config` との互換性問題を解消（必要に応じて個別ルールを override） +3. CI から `continue-on-error: true` を削除 + +## lint-staged に ESLint 追加 + +```json +{ + "*.{ts,tsx}": ["eslint --fix", "prettier --write"], + "*.{js,jsx,md,json,yaml,yml}": ["prettier --write"] +} +``` + +## pre-push hook + +```bash +pnpm test && pnpm -r exec tsc --noEmit +``` + +## Claude Code ワークフロー + +config リポジトリの `.github/workflows/claude.yml` をテンプレートとして追加。 + +## CLAUDE.md + +**含めるべき内容**: + +- **構成**: pnpm workspaces monorepo（`extensions/*`） +- **拡張一覧**: 各拡張の名前と用途 +- **Raycast API**: 各拡張が `@raycast/api` + `@raycast/utils` に依存 +- **ESLint**: `@raycast/eslint-config` を各拡張で継承 +- **commitlint**: `subject-case` を無効化（日本語コミットメッセージ対応） +- **テスト戦略**: Raycast API モック + ロジック層分離パターン +- **リリース**: 日付ベースバージョニング（`v{YYYY.MM.DD}-{short-sha}`） + +## DevContainer + +- **ベースイメージ**: `ghcr.io/keito4/config-base:latest` +- **冗長 Features の削除**: ベースイメージに含まれるもの（github-cli, pnpm, jq-likes）は削除 +- **残すべき Features**: `docker-in-docker`（プロジェクト固有） diff --git a/docs/setup/mobile-android.md b/docs/setup/mobile-android.md new file mode 100644 index 00000000..e4dda382 --- /dev/null +++ b/docs/setup/mobile-android.md @@ -0,0 +1,99 @@ +# モバイル (Android) セットアップガイド + +## detekt（Kotlin 静的解析） + +```kotlin +// build.gradle.kts (ルート) +plugins { + id("io.gitlab.arturbosch.detekt") version "1.23.7" apply false +} + +// app/build.gradle.kts +plugins { + id("io.gitlab.arturbosch.detekt") +} + +detekt { + buildUponDefaultConfig = true + config.setFrom("$rootDir/config/detekt.yml") +} +``` + +```yaml +# CI +- name: Run detekt + run: ./gradlew detekt +``` + +## Kover（カバレッジ 70%） + +```kotlin +// app/build.gradle.kts +plugins { + id("org.jetbrains.kotlinx.kover") version "0.9.1" +} + +kover { + reports { + verify { + rule { + minBound(70) + } + } + } +} +``` + +```yaml +# CI +- name: Run tests with coverage + run: ./gradlew koverVerify +- name: Generate coverage report + run: ./gradlew koverHtmlReport +``` + +## CLAUDE.md + +**含めるべき内容**: + +- **技術スタック**: Kotlin / Jetpack Compose / DI フレームワーク / DB / Coroutines +- **アーキテクチャ**: レイヤー分離の方針（domain/data/presentation 等） +- **依存管理**: Version Catalog (`gradle/libs.versions.toml`) の運用方針 +- **テスト戦略**: Unit テスト（JUnit + アサーション + モック）、Integration テストのフレームワーク +- **リリースフロー**: CI でのバージョン管理とデプロイ先 +- **ビルド設定**: バージョン管理の仕組み + +## commitlint（lefthook） + +Android プロジェクトは JVM 非依存の lefthook を推奨。 + +```yaml +# lefthook.yml +commit-msg: + commands: + commitlint: + run: 'echo "{1}" | npx commitlint --edit' +``` + +## Claude Code ワークフロー + +config リポジトリの `.github/workflows/claude.yml` をテンプレートとして追加。 + +## CodeQL + +```yaml +- name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: java-kotlin +- name: Build + run: ./gradlew assembleDebug +- name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 +``` + +## DevContainer + +- **ベースイメージ**: `ghcr.io/keito4/config-base:latest` +- **Features**: `java(17)` + Gradle — Android 固有のため維持 +- **postCreateCommand**: `sdkmanager --install 'platforms;android-35' ...` diff --git a/docs/setup/mobile-flutter.md b/docs/setup/mobile-flutter.md new file mode 100644 index 00000000..78fd83c8 --- /dev/null +++ b/docs/setup/mobile-flutter.md @@ -0,0 +1,65 @@ +# モバイル (Flutter) セットアップガイド + +## CI カバレッジ閾値強制 + +```yaml +- name: Check coverage threshold + run: | + COVERAGE=$(lcov --summary coverage/lcov.info 2>&1 \ + | grep "lines" | grep -oP '[\d.]+%' | head -1 | tr -d '%') + if (( $(echo "$COVERAGE < 70" | bc -l) )); then + echo "Coverage $COVERAGE% is below 70% threshold" + exit 1 + fi + echo "Coverage: $COVERAGE%" +``` + +> 代替: `very_good_cli` の `very_good test --min-coverage 70` も利用可能。 + +## CI フォーマット検証 + +```yaml +- name: Format check + run: dart format --set-exit-if-changed . +``` + +## commitlint（lefthook） + +Flutter プロジェクトは Node.js 非依存の lefthook を推奨。 + +```bash +brew install lefthook +``` + +```yaml +# lefthook.yml +commit-msg: + commands: + commitlint: + run: 'echo "{1}" | npx commitlint --edit' + +pre-commit: + commands: + format: + run: dart format --set-exit-if-changed . + analyze: + run: flutter analyze +``` + +## Claude Code ワークフロー + +config リポジトリの `.github/workflows/claude.yml` をテンプレートとして追加。 + +## CodeQL / SAST + +Dart 向けの CodeQL は限定的だが、依存関係スキャンは有効。 + +## release-please のブランチ名確認 + +`release-please.yml` のトリガーブランチがリポジトリのデフォルトブランチ（`main` or `master`）と一致していることを確認する。 + +## DevContainer + +- **ベースイメージ**: `ghcr.io/keito4/config-base:latest` +- **Features**: `flutter`, `java(17)` — Flutter 固有のため維持 +- **postCreateCommand**: `flutter pub get && dart run build_runner build --delete-conflicting-outputs` diff --git a/docs/setup/npm-library-cli.md b/docs/setup/npm-library-cli.md new file mode 100644 index 00000000..1ef3b10d --- /dev/null +++ b/docs/setup/npm-library-cli.md @@ -0,0 +1,87 @@ +# npm ライブラリ (CLI) セットアップガイド + +## commitlint + +semantic-release と組み合わせて Conventional Commits を強制する。 + +```bash +pnpm add -D @commitlint/cli @commitlint/config-conventional +``` + +**設定ファイル** (`commitlint.config.js`): + +```js +export default { extends: ['@commitlint/config-conventional'] }; +``` + +**husky hook 追加**: + +```bash +echo 'pnpm commitlint --edit "$1"' > .husky/commit-msg +``` + +**参考**: `/setup-husky` コマンドで commitlint を含む構成を導入可能。 + +## カバレッジ閾値 70% + +```js +// jest.config.js +coverageThreshold: { + global: { branches: 70, functions: 70, lines: 70, statements: 70 }, +}, +``` + +閾値が低い場合は +10% ずつ段階的に引き上げる。 + +## CI に `format:check` ステップ追加 + +```yaml +- name: Format check + run: pnpm format:check +``` + +## lint-staged + +```bash +pnpm add -D lint-staged +``` + +```json +{ + "*.{ts,tsx}": ["eslint --fix", "prettier --write"], + "*.{json,md,yml}": ["prettier --write"] +} +``` + +**`.husky/pre-commit` を更新**: + +```bash +pnpm exec lint-staged +``` + +## CLAUDE.md + +**含めるべき内容**: + +- **用途**: ライブラリ / CLI の概要 +- **技術スタック**: TypeScript バージョン、主要依存パッケージ +- **テスト戦略**: テストフレームワーク、ESM モック化の要否 +- **リリースフロー**: semantic-release の設定と対象ブランチ +- **ビルド**: `tsc` → `dist/` の設定、declaration の有無 +- **公開設定**: `bin`、`files`、`exports` の構成 + +## ESLint Flat Config 統一 + +`.eslintrc.js` と `eslint.config.mjs` が共存している場合、Flat Config (`eslint.config.mjs`) に統一し `.eslintrc.js` を削除する。 + +**手順**: + +1. `.eslintrc.js` の内容を確認し、`eslint.config.mjs` に未反映のルールがないか検証 +2. `tsconfig.eslint.json`（`.eslintrc.js` 用）の参照を確認 +3. `.eslintrc.js` と不要な `tsconfig.eslint.json` を削除 +4. `pnpm lint` で正常動作を確認 + +## DevContainer + +- **ベースイメージ**: `ghcr.io/keito4/config-base:latest` +- **冗長 Features の削除**: ベースイメージに含まれるもの（node, gh 等）は更新後に削除を検討 diff --git a/docs/setup/spa-react-vite.md b/docs/setup/spa-react-vite.md new file mode 100644 index 00000000..e6ced3d9 --- /dev/null +++ b/docs/setup/spa-react-vite.md @@ -0,0 +1,96 @@ +# SPA (React + Vite) セットアップガイド + +## テスト環境（Vitest） + +```bash +npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom @vitest/coverage-v8 @vitejs/plugin-react +``` + +> 注: `@vitejs/plugin-react` はテスト環境（jsdom）で React コンポーネントをレンダリングするために必要。 + +**設定例** (`vitest.config.ts`): + +```ts +import { defineConfig } from 'vitest/config'; +import react from '@vitejs/plugin-react'; + +export default defineConfig({ + plugins: [react()], + test: { + environment: 'jsdom', + setupFiles: ['./src/test/setup.ts'], + coverage: { + provider: 'v8', + thresholds: { lines: 70, branches: 70, functions: 70, statements: 70 }, + }, + }, + resolve: { + alias: { '@': '.' }, + }, +}); +``` + +> `resolve.alias` は `tsconfig.json` の `paths: { "@/*": ["./*"] }` と合わせる。 + +**スクリプト**: + +```json +{ + "test": "vitest run", + "test:watch": "vitest", + "test:coverage": "vitest run --coverage" +} +``` + +## ESLint + Prettier + +```bash +npm install -D eslint @eslint/js typescript-eslint eslint-plugin-react-hooks eslint-plugin-react-refresh eslint-config-prettier +npm install -D prettier +``` + +**スクリプト**: + +```json +{ + "lint": "eslint .", + "lint:fix": "eslint . --fix", + "format": "prettier --write .", + "format:check": "prettier --check ." +} +``` + +## CI/CD ワークフロー + +**参考**: `/setup-ci` コマンドで雛形を生成可能。 + +``` +Lint → Format Check → Test (with coverage) → Build +``` + +## husky + commitlint + +**参考**: `/setup-husky` コマンドで最小構成を導入可能。 + +## lint-staged + +```json +{ + "*.{ts,tsx}": ["eslint --fix", "prettier --write"], + "*.{json,md,yml}": ["prettier --write"] +} +``` + +## CLAUDE.md + +**含めるべき内容**: + +- **用途**: アプリケーションの概要 +- **技術スタック**: React / Vite / TypeScript のバージョン、主要ライブラリ +- **環境変数**: 必要な API キーと管理方法（`.env.local`） +- **コンポーネント設計**: ディレクトリ構成と設計方針 +- **パスエイリアス**: `@/*` の解決先 + +## DevContainer + +- **ベースイメージ**: `ghcr.io/keito4/config-base:latest` diff --git a/docs/setup/web-app-nextjs.md b/docs/setup/web-app-nextjs.md new file mode 100644 index 00000000..2b73a1b6 --- /dev/null +++ b/docs/setup/web-app-nextjs.md @@ -0,0 +1,278 @@ +# Web アプリ (Next.js) セットアップガイド + +## テスト環境構築とカバレッジ 70% 達成 + +テストフレームワークの選択は 2 パターンが確立されている。 + +**パターン A: Jest + Testing Library** + +```bash +npm install -D jest @jest/globals jest-environment-jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @types/jest +``` + +`jest.config.js`（`next/jest` を利用）: + +```js +const nextJest = require('next/jest'); +const createJestConfig = nextJest({ dir: './' }); + +module.exports = createJestConfig({ + coverageProvider: 'v8', + testEnvironment: 'jsdom', + setupFilesAfterSetup: ['/jest.setup.js'], + moduleNameMapper: { '^@/(.*)$': '/$1' }, + coverageThreshold: { + global: { branches: 70, functions: 70, lines: 70, statements: 70 }, + }, +}); +``` + +**パターン B: Vitest** + +```bash +npm install -D vitest @vitest/coverage-v8 @testing-library/react @testing-library/jest-dom jsdom +``` + +`vitest.config.ts`: + +```ts +import { defineConfig } from 'vitest/config'; +import react from '@vitejs/plugin-react'; + +export default defineConfig({ + plugins: [react()], + test: { + environment: 'jsdom', + coverage: { + provider: 'v8', + thresholds: { lines: 70, branches: 70, functions: 70, statements: 70 }, + }, + }, +}); +``` + +**既存プロジェクトのカバレッジ引き上げ**: + +1. `npm run test:coverage` で現在の実カバレッジを計測 +2. 各指標を +10% ずつ段階的に引き上げ +3. 最終目標: 全指標 70% + +## Biome（Lint + Format） + +ESLint + Prettier の代わりに **Biome を推奨**する。1 ツールで lint + format を高速に実行できる。 + +```bash +npm install -D --save-exact @biomejs/biome +npx @biomejs/biome init +``` + +`biome.json`: + +```json +{ + "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json", + "organizeImports": { + "enabled": true + }, + "formatter": { + "indentStyle": "space", + "indentWidth": 2, + "lineWidth": 100 + }, + "linter": { + "rules": { + "recommended": true + } + }, + "files": { + "ignore": [".next", "node_modules", "coverage"] + } +} +``` + +**推奨スクリプト**: + +```json +{ + "check": "biome check .", + "check:fix": "biome check --write .", + "lint": "biome lint .", + "format": "biome format .", + "format:check": "biome format ." +} +``` + +> `biome check` は lint + format + import 整理を一括実行する。CI では `biome check .` を使う。 + +### 既存の ESLint + Prettier からの移行 + +```bash +npx @biomejs/biome migrate eslint +npx @biomejs/biome migrate prettier +``` + +移行後、不要になったパッケージと設定ファイルを削除する: + +- `eslint`, `eslint-config-*`, `eslint-plugin-*`, `@eslint/*`, `typescript-eslint` +- `prettier`, `eslint-config-prettier` +- `eslint.config.mjs` / `.eslintrc.*` / `.prettierrc*` + +## Knip（未使用コード検出） + +未使用の依存関係・ファイル・export を検出する **Knip を推奨**する。 + +```bash +npm install -D knip +``` + +`knip.json`: + +```json +{ + "$schema": "https://unpkg.com/knip@5/schema.json", + "ignore": ["!src/generated/**"], + "ignoreDependencies": [], + "next": { + "entry": ["next.config.{js,ts,mjs}", "src/app/**/*.{ts,tsx}", "src/middleware.ts"] + } +} +``` + +> Knip は Next.js プラグインを内蔵しており、`next.config.*` や App Router のエントリを自動検出する。 + +**推奨スクリプト**: + +```json +{ + "knip": "knip" +} +``` + +CI にも追加: + +```yaml +- name: Check unused code + run: npm run knip +``` + +## CI/CD パイプライン + +``` +typecheck → biome check → knip → test (coverage) → build → e2e → security +``` + +**最小構成** (`ci.yml`): + +```yaml +jobs: + typecheck: + steps: + - run: npm run typecheck + quality: + steps: + - run: npx biome check . + - run: npm run knip + test: + steps: + - run: npm run test:ci + build: + needs: [typecheck, quality, test] + steps: + - run: npm run build +``` + +**発展構成**（ワークフロー分割）: + +- `code-quality.yml`: typecheck + biome check + knip +- `security.yml`: npm audit + CodeQL +- `deploy.yml`: Vercel / その他プラットフォーム + +## husky + commitlint + lint-staged + +**参考**: `/setup-husky` コマンドで最小構成を導入可能。 + +```bash +npm install -D husky @commitlint/cli @commitlint/config-conventional lint-staged +``` + +**commitlint.config.js**: + +```js +module.exports = { + extends: ['@commitlint/config-conventional'], + rules: { + 'body-max-line-length': [2, 'always', 120], + }, +}; +``` + +**lint-staged.config.js**: + +```js +module.exports = { + '*.{ts,tsx,js,jsx,json,css}': ['biome check --write --no-errors-on-unmatched'], + '*.{md,yml,yaml}': ['biome format --write --no-errors-on-unmatched'], +}; +``` + +**pre-push hook**: + +```bash +npm run typecheck && npx biome check . && npm run test +``` + +## CLAUDE.md + +**含めるべき内容**: + +- **技術スタック**: Next.js バージョン、React バージョン、CSS フレームワーク（Tailwind CSS 3/4） +- **バックエンド連携**: Supabase / Firebase / 外部 API の構成 +- **テスト戦略**: Jest or Vitest の選択理由、E2E の有無 +- **デプロイ先**: Vercel / その他 +- **品質ゲート**: pre-commit / pre-push の実行内容 + +## E2E テスト（Playwright） + +```bash +npm install -D @playwright/test +npx playwright install +``` + +**playwright.config.ts**: + +```ts +export default defineConfig({ + testDir: './tests/e2e', + fullyParallel: true, + forbidOnly: !!process.env.CI, + retries: process.env.CI ? 2 : 0, + workers: process.env.CI ? 1 : undefined, + projects: process.env.CI + ? [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }] + : [ + { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, + { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, + { name: 'webkit', use: { ...devices['Desktop Safari'] } }, + ], + webServer: { + command: 'npm run dev', + url: 'http://localhost:3000', + reuseExistingServer: true, + }, +}); +``` + +> CI では Chromium のみに限定しフィードバックを高速化する。 + +## Claude Code ワークフロー + +- `claude.yml`: `@claude` メンション対応 +- `claude-code-review.yml`: PR 自動レビュー + +**参考**: config リポジトリの `.github/workflows/claude.yml` をテンプレートとして使用。 + +## DevContainer + +- **ベースイメージ**: `ghcr.io/keito4/config-base:latest` +- **冗長 Features の削除**: ベースイメージに含まれるもの（git, pnpm, github-cli, jq-likes, supabase-cli）は削除 +- **残すべき Features**: docker-in-docker, playwright（プロジェクト固有） diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md new file mode 100644 index 00000000..7f8b3f35 --- /dev/null +++ b/docs/tool-catalog.md @@ -0,0 +1,228 @@ +# Tool Catalog + +環境×ツールのマトリクスを一覧化し、各リポジトリのツール構成を可視化する。 + +## 1. ツール管理の4レイヤー構造 + +``` +Layer 4: macOS ローカル (Brewfile) + ├─ GUI アプリ、OS レベルの CLI、VS Code 拡張 +Layer 3: プロジェクト依存 (package.json / pubspec.yaml / build.gradle) + ├─ フレームワーク、テストライブラリ、リンター +Layer 2: DevContainer Features (devcontainer.json) + ├─ クラウド CLI、追加ランタイム、インフラツール +Layer 1: ベースイメージ (ghcr.io/keito4/config-base) + └─ Node.js, Rust, Python, AI CLI, Language Servers +``` + +| レイヤー | 管理場所 | 更新頻度 | 影響範囲 | +| -------------------- | --------------------------------- | ---------- | ------------ | +| L1: ベースイメージ | `config/.devcontainer/Dockerfile` | リリース時 | 全リポジトリ | +| L2: Features | 各 `devcontainer.json` | リポ個別 | 当該リポのみ | +| L3: プロジェクト依存 | `package.json` 等 | 開発中随時 | 当該リポのみ | +| L4: macOS ローカル | `brew/MacOSBrewfile` | 手動 | ローカルのみ | + +## 2. ベースイメージ (`config-base`) に含まれるツール + +### 2.1 ランタイム + +| ツール | バージョン | 用途 | +| ------------- | --------------------- | -------------------------- | +| Node.js | 22.14.0 | JavaScript/TypeScript 実行 | +| Rust (stable) | rustup 管理 | CLI ツールビルド | +| Python 3 | apt 管理 | スクリプト、AI ツール | +| pnpm | npm 経由で最新 | パッケージマネージャ | +| npm | 11.10.0 (global.json) | パッケージマネージャ | +| corepack | 0.34.6 (global.json) | パッケージマネージャ切替 | + +### 2.2 AI CLI ツール + +| ツール | バージョン管理 | 用途 | +| --------------------------------- | ------------------------- | ------------------- | +| Claude Code | native installer (2.1.42) | AI コーディング支援 | +| Codex (`@openai/codex`) | 0.101.0 (global.json) | OpenAI Codex CLI | +| Gemini CLI (`@google/gemini-cli`) | 0.28.2 (global.json) | Google Gemini CLI | +| Happy Coder | 0.13.0 (global.json) | AI コーディング | +| Cursor | curl installer | AI エディタ CLI | + +### 2.3 ユーティリティ + +| ツール | バージョン | 用途 | +| ------------- | --------------------- | -------------------- | +| shellcheck | apt 管理 | シェルスクリプト検証 | +| Doppler CLI | 3.75.2 | シークレット管理 | +| similarity-ts | cargo install | コード類似度分析 | +| eslint | npm global | JavaScript リンター | +| Supabase CLI | pnpm global | Supabase 操作 | +| Vercel CLI | 50.17.1 (global.json) | Vercel デプロイ | +| n8n | 2.7.5 (global.json) | ワークフロー自動化 | +| pm2 | 6.0.14 (global.json) | プロセスマネージャ | + +### 2.4 Language Servers（global.json） + +| パッケージ | バージョン | 対象言語 | +| ---------------------------- | ---------- | --------------------- | +| typescript | 5.9.3 | TypeScript コンパイラ | +| typescript-language-server | 5.1.3 | TypeScript LSP | +| bash-language-server | 5.6.0 | Bash LSP | +| vscode-langservers-extracted | 4.10.0 | HTML/CSS/JSON LSP | +| yaml-language-server | 1.19.2 | YAML LSP | + +### 2.5 MCP / Automation + +| パッケージ | バージョン | 用途 | +| ------------------------------- | ---------- | ---------------- | +| mcp-remote | 0.1.38 | MCP リモート接続 | +| `@leonardsellem/n8n-mcp-server` | 0.1.8 | n8n MCP サーバー | +| `@mseep/linear-mcp` | 78.0.1 | Linear MCP 連携 | + +### 2.6 Git / CI 関連（Dockerfile 末尾でインストール） + +| パッケージ | バージョン | 用途 | +| --------------------------------- | ---------- | ---------------------- | +| husky | 9.1.7 | Git hooks | +| `@commitlint/cli` | 20.4.1 | コミットメッセージ検証 | +| `@commitlint/config-conventional` | 20.4.1 | Conventional Commits | + +## 3. DevContainer Features（config ベースで提供） + +`config/.devcontainer/devcontainer.json` に定義されている Features: + +| Feature | 用途 | +| -------------------------------------- | ----------------------------- | +| `homebrew-package` | Homebrew パッケージマネージャ | +| `jq-likes` (jq/yq) | JSON/YAML 処理 | +| `node` (+ pnpm latest) | Node.js（追加バージョン） | +| `1password` | シークレット管理 | +| `github-cli` | GitHub CLI (`gh`) | +| `git` | Git（最新版） | +| `terraform` | IaC | +| `google-cloud-cli` | GCP CLI | +| `aws-cli` | AWS CLI | +| `kubectl-helm-minikube` (kubectl 1.28) | Kubernetes 操作 | +| `act` | GitHub Actions ローカル実行 | +| `deno` | Deno ランタイム | +| `docker-in-docker` (moby + compose v2) | Docker-in-Docker | +| `playwright` | ブラウザ自動テスト | +| `supabase-cli` | Supabase CLI | + +> **Codespaces 用** (`codespaces/devcontainer.json`) は上記 + `sshd` Feature を追加。 + +## 4. リポジトリ×ツール マトリクス + +### 4.1 DevContainer 利用リポジトリ + +| | 共通基盤 (config) | Web アプリ (Next.js) | npm ライブラリ (CLI) | SPA (React + Vite) | デスクトップ拡張 (TS) | モバイル (Flutter) | モバイル (Android) | +| ---------------------- | ------------------ | --------------------------------------------- | -------------------- | ------------------ | --------------------- | ---------------------- | ------------------ | +| **ベースイメージ ver** | ローカルビルド | 1.54.0 | 1.0.13 | 1.0.13 | 1.58.0 | 1.0.13 | 1.0.13 | +| **言語** | JS/Shell | TypeScript | TypeScript | TypeScript | TypeScript | Dart/Flutter | Kotlin | +| **フレームワーク** | - | Next.js 15 | - (CLI) | React 19 + Vite | Raycast API | Flutter 3.27 | Jetpack Compose | +| **PKG マネージャ** | npm | npm | pnpm | npm | pnpm | pub | Gradle | +| **テスト (Unit)** | Jest + BATS | Jest | Jest | - | - | flutter_test + mockito | - | +| **テスト (E2E)** | - | Playwright | - | - | - | Patrol | - | +| **リンター** | ESLint | ESLint + next lint | ESLint | - | - | very_good_analysis | - | +| **フォーマッター** | Prettier | Prettier | Prettier | - | Prettier | dart format | - | +| **Git hooks** | husky + commitlint | husky + commitlint | husky | - | husky + commitlint | - | - | +| **CI/CD** | GitHub Actions | GitHub Actions | GitHub Actions | - | GitHub Actions | GitHub Actions | - | +| **追加 Features** | 全 Features | git, pnpm, gh, jq, supabase, dind, playwright | node(20), gh | - | gh, dind, pnpm, jq | flutter, java(17) | java(17) + gradle | + +### 4.2 主要な追加依存（注目ポイント） + +| 種別 | 注目する依存 | +| --------------------- | ------------------------------------------------------------------------------ | +| 共通基盤 (config) | semantic-release, jest-junit, bats | +| Web アプリ (Next.js) | `@supabase/ssr`, Tailwind CSS 4, Zod 4, Testing Library, Playwright, LangSmith | +| npm ライブラリ (CLI) | `@notionhq/client`, commander, ts-jest, semantic-release | +| SPA (React + Vite) | `@google/genai`, D3.js, React 19 | +| デスクトップ拡張 (TS) | lint-staged, monorepo (pnpm workspaces) | +| モバイル (Flutter) | Riverpod, Drift (SQLite), Freezed, go_router | + +## 5. macOS ローカルツール（Brewfile） + +`brew/MacOSBrewfile` より抽出。 + +### 5.1 開発ツール (brew) + +| カテゴリ | ツール | +| --------------- | ------------------------------------------- | +| 言語/ランタイム | node, deno, php, openjdk, pipenv, uv | +| VCS/Git | git, gh, ghq, tig | +| ユーティリティ | jq, fzf, peco, tree, coreutils, trash, gawk | + +### 5.2 Cloud / DevOps (brew) + +| ツール | 用途 | +| --------------------------------- | ------------------ | +| awscli, aws-sam-cli, aws-sso-util | AWS | +| azure-cli | Azure | +| gcloud-cli (cask) | GCP | +| terraform, tfenv | IaC | +| helm | Kubernetes | +| docker | コンテナ | +| sops | シークレット暗号化 | +| supabase | BaaS | + +### 5.3 Cask アプリケーション（抜粋） + +| カテゴリ | アプリ | +| ------------ | -------------------------------------------------------- | +| 開発 | Visual Studio Code, Cursor, TablePlus, OrbStack, Rancher | +| AI | ChatGPT, Claude | +| 通信 | Slack, Discord, Mattermost, Zoom | +| 生産性 | Notion, Raycast, Alfred, BetterTouchTool, Karabiner | +| セキュリティ | 1Password, 1Password CLI, Tailscale | +| ブラウザ | Arc | + +### 5.4 VS Code 拡張機能（抜粋・カテゴリ別） + +| カテゴリ | 拡張機能 | +| -------- | ---------------------------------------------------------------------------------------------- | +| AI | `anthropic.claude-code`, `github.copilot`, `github.copilot-chat`, `openai.chatgpt` | +| 言語 | `dbaeumer.vscode-eslint`, `esbenp.prettier-vscode`, `denoland.vscode-deno`, `prisma.prisma` | +| インフラ | `4ops.terraform`, `ms-kubernetes-tools.vscode-kubernetes-tools`, `ms-azuretools.vscode-docker` | +| Remote | `ms-vscode-remote.remote-containers`, `ms-vscode-remote.remote-ssh`, `github.codespaces` | +| Python | `ms-python.python`, `ms-python.vscode-pylance`, `ms-python.isort` | +| Ruby | `shopify.ruby-lsp`, `rebornix.ruby` | + +## 6. 所見・改善提案 + +### 6.1 ベースイメージバージョンの乖離 + +4 リポジトリ（npm ライブラリ、SPA、モバイル Flutter、モバイル Android）が **1.0.13** のまま。 +最新は **1.58.0+** であり、AI CLI やセキュリティパッチが大幅に遅れている。 + +> **推奨**: `/config-base-sync-update` コマンドで一括更新、または Dependabot/Renovate で自動化。 + +### 6.2 Features の重複 + +Web アプリ、デスクトップ拡張で `pnpm`, `gh`, `jq` などベースイメージに含まれるツールを Features で再インストールしている。 +ベースイメージ更新後は Features の棚卸しが必要。 + +### 6.3 テスト未設定のリポジトリ + +| 種別 | 状態 | +| --------------------- | ---------------------------------------------- | +| SPA (React + Vite) | Unit / E2E ともに未設定 | +| デスクトップ拡張 (TS) | テストスクリプトなし（Raycast 固有の制約あり） | +| モバイル (Android) | テスト未設定 | + +> **推奨**: TDD ベースライン（70%+ カバレッジ）に合わせ、最低限 Unit テストを追加。 + +### 6.4 リンター/フォーマッター未設定 + +SPA (React + Vite) とモバイル (Android) は lint / format スクリプトが未定義。 +コード品質の最低保証が欠けている。 + +### 6.5 Brewfile の肥大化 + +`MacOSBrewfile` は **232 行**に達しており、使用頻度の低いツールが混在。 +`categories.json` による分類は存在するが、定期的な棚卸しルールがない。 + +> **推奨**: 四半期ごとに `brew uses --installed` で利用状況を確認し、不要パッケージを削除。 + +### 6.6 Git hooks の統一 + +共通基盤、Web アプリ、npm ライブラリは husky + commitlint を使用しているが、 +SPA、モバイル (Flutter/Android) では Git hooks が未設定。 + +> **推奨**: `/setup-husky` コマンドで Conventional Commits を全リポに展開。