========================================================================
Pixel Paint War - 管理者用環境構築手順 (Admin Setup Guide)
========================================================================

1. はじめに (Introduction)
------------------------------------------------------------------------
    本ドキュメントは，プロジェクトを「ゼロから新規作成・再構築する管理者」向けの
    Monorepo構成およびDocker環境の構築ログである．
    ※ 一般の開発メンバー（Git Cloneして参加する人）は本ドキュメントを実施不要である．

2. 管理者用事前準備 (Prerequisites for Admin)
------------------------------------------------------------------------
    
2-1. プロジェクト作成用ツールのインストール
    1. Node.js (v20.x LTS)
        ・Nodesource リポジトリを使用してインストールする．
        
        # リポジトリのセットアップとインストール
        $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
        $ sudo apt-get install -y nodejs

        ・確認コマンド:
        $ node -v  # v20.x.x と表示されること

    2. pnpm (Package Manager)
        ・Node.js 標準の npm ではなく pnpm を使用する．
        ・Corepack (Node.js同梱) を有効化してインストールする．
        $ sudo corepack enable
        $ corepack prepare pnpm@latest --activate

        ・確認コマンド:
        $ pnpm -v


3. 新規プロジェクト構築 (Project Initialization)
------------------------------------------------------------------------

3-1. プロジェクト初期化
    1. ディレクトリ作成
        $ mkdir SkillSemiWebGame
        $ cd SkillSemiWebGame

    2. Git/pnpm 初期化
        $ git init
        $ pnpm init

3-2. Monorepo構成設定
    1. pnpm-workspace.yaml 作成
        ルート直下に作成し、以下を記述する．
        packages:
          - 'apps/*'
          - 'packages/*'

    2. .npmrc 作成
        ルート直下に作成し、以下を記述する．
        shamefully-hoist=true

3-3. ディレクトリ構造の構築
    以下の構成になるようにディレクトリを作成する．

    root/
    ├── apps/
    │   ├── client/           # フロントエンド (Browser)
    │   └── server/           # バックエンド (Node.js)
    └── packages/
        └── shared/           # 共通ロジック (Shared Library)

    ・作成コマンド例:
        $ mkdir -p apps/client apps/server packages/shared

3-4. Git除外設定 (.gitignore)
    ルート直下に `.gitignore` を作成し、以下を記述する．

    node_modules/
    .pnpm-store/
    dist/
    build/
    .env
    .DS_Store
    .vscode/*
    !.vscode/extensions.json
    !.vscode/launch.json
    coverage/
    !packages/


4. アプリケーション雛形の作成 (Scaffolding)
------------------------------------------------------------------------

4-1. 共通ライブラリ (packages/shared)
    1. 初期化とビルドツール導入
        $ cd packages/shared
        $ pnpm init
        $ pnpm add -D typescript tsup

    2. 設定ファイルの調整 (package.json)
        ・name: "@repo/shared" と命名する（推奨）．
        ・main: "./dist/index.js", types: "./dist/index.d.ts" を指定する．
        ・scripts: "build": "tsup src/index.ts --format cjs,esm --dts" を追加する．

    3. エントリーポイントの作成
        $ mkdir src
        $ touch src/index.ts
        ※ (例: export * from './constants';)

    4. TypeScript設定ファイルの作成 (tsconfig.json)
        ・ファイル: packages/shared/tsconfig.json
        ・内容:
            {
              "compilerOptions": {
                "target": "ES2020",
                "module": "ESNext",
                "moduleResolution": "Bundler",
                "lib": ["ES2020", "DOM", "DOM.Iterable"],
                "declaration": true,
                "declarationMap": true,
                "sourceMap": true,
                "outDir": "./dist",
                "rootDir": "./src",
                "strict": true,
                "esModuleInterop": true,
                "skipLibCheck": true,
                "forceConsistentCasingInFileNames": true
              },
              "include": ["src/**/*"],
              "exclude": ["node_modules", "dist"]
            }

4-2. フロントエンド (apps/client)
    1. プロジェクト作成
        $ cd ../../apps/client
        $ pnpm create vite . --template preact-ts
        ※ Use rolldown-vite? » No
        ※ Install with pnpm and start now? » No

    2. 依存ライブラリのインストール
        $ pnpm add pixi.js
        $ pnpm add @repo/shared --workspace

4-3. バックエンド (apps/server)
    1. 初期化
        $ cd ../../apps/server
        $ pnpm init

    2. 依存ライブラリのインストール
        $ pnpm add ws
        $ pnpm add -D tsx typescript @types/node @types/ws
        $ pnpm add @repo/shared --workspace
    
    3. サーバー用ディレクトリとファイルの作成
        $ mkdir src
        $ touch src/index.ts
    
    4. 実行スクリプトの定義 (package.json)
        "scripts": {
          "dev": "tsx watch src/index.ts"
        }
    
    5. TypeScript設定ファイルの作成 (tsconfig.json)
        ・ファイル: apps/server/tsconfig.json
        ・内容:
            {
              "compilerOptions": {
                "target": "ES2022",
                "module": "NodeNext",
                "moduleResolution": "NodeNext",
                "lib": ["ES2022"],
                "strict": true,
                "noEmit": true,
                "esModuleInterop": true,
                "skipLibCheck": true,
                "forceConsistentCasingInFileNames": true,
                "baseUrl": ".",
                "paths": {
                  "@repo/shared": ["../../packages/shared/src/index.ts"]
                }
              },
              "include": ["src/**/*"],
              "exclude": ["node_modules"]
            }

4-4. 初回コミット (Initial Commit)
    1. ルートに戻る
        $ cd ../..
    2. ステータスの確認 (node_modulesが含まれていないこと)
        $ git status
    3. Gitへ保存
        $ git add .
        $ git commit -m "chore: Initialize project structure and dependencies"


5. Docker環境定義ファイルの作成 (Configuration)
------------------------------------------------------------------------

5-1. Dockerfile の作成
    プロジェクトルートに `Dockerfile` を作成する．
    ※ Node.js v20 をベースとし，pnpm を有効化した開発用イメージ定義．

    FROM node:20-slim

    # pnpmの準備
    ENV PNPM_HOME="/pnpm"
    ENV PATH="$PNPM_HOME:$PATH"
    RUN corepack enable

    # 作業ディレクトリ設定
    WORKDIR /workspace

    # 依存関係のコピーとインストール (キャッシュ活用)
    COPY . .
    RUN pnpm install

    # ポート公開 (Vite:5173, Server:3000)
    EXPOSE 5173 3000

    # デフォルトコマンド (docker-composeで上書きするため待機)
    CMD ["sleep", "infinity"]

5-2. docker-compose.yml の作成 (開発用)
    プロジェクトルートに `docker-compose.yml` を作成する．
    ※ ローカルのソースコードをコンテナにマウントする設定．

    version: "3.8"

    services:
      app:
        container_name: pixel-paint-war-dev
        # 開発用イメージ: Node.js v20 (定義書準拠)
        image: mcr.microsoft.com/devcontainers/typescript-node:20

        # 永続化とボリュームマウント
        volumes:
          # カレントディレクトリをコンテナ内の /workspace にマウント
          - .:/workspace:cached
          # 【重要】node_modules をホスト側と切り離して高速化・安定化させる設定
          - node_modules:/workspace/node_modules

        # コマンドの上書き (コンテナを常時起動させる)
        command: sleep infinity

        # ネットワーク設定
        # Client(5173) と Server(3000) のポートを開放
        ports:
          - "5173:5173"
          - "3000:3000"

        # 環境変数
        environment:
          - NODE_ENV=development

        # ユーザー権限 (Nodeイメージ推奨のユーザー)
        user: node

    volumes:
      node_modules:

5-3. .devcontainer 設定の作成
    1. ディレクトリ作成
        $ mkdir .devcontainer
    
    2. .devcontainer/devcontainer.json 作成
        VS Codeがコンテナを認識するための設定．

    {
      "name": "Pixel Paint War Dev",
      "dockerComposeFile": "../docker-compose.yml",
      "service": "app",
      "workspaceFolder": "/workspace",

      "features": {
        "ghcr.io/devcontainers/features/node:1": {
          "version": "20",
          "pnpm": "latest"
        }
      },

      "customizations": {
        "vscode": {
          "extensions": [
            "dbaeumer.vscode-eslint",
            "esbenp.prettier-vscode",
            "editorconfig.editorconfig",
            "ms-vscode.hexeditor",
            "github.copilot",
            "github.copilot-chat"
          ],
          "settings": {
            "editor.formatOnSave": true,
            "editor.defaultFormatter": "esbenp.prettier-vscode"
          }
        }
      },

      // コンテナ起動後の初期化コマンド
      // 1. sudo chown ... : node_modules の所有権を node ユーザーに強制変更
      // 2. pnpm install   : その後，安全にインストールを実行
      // 3. build          : 最後に共通パッケージをビルド
      "postCreateCommand": "sudo chown -R node:node /workspace/node_modules && pnpm install && pnpm --filter @repo/shared build",

      // コンテナ内のユーザー
      "remoteUser": "node"
    }

5-4. docker-compose.prod.yml の作成 (本番確認用)
    プロジェクトルートに `docker-compose.prod.yml` を作成する．
    ※ 本番ビルド確認用にポートをずらし、ビルドコマンドを実行する設定．

    services:
      app:
        build: .
        ports:
          - "3001:3000"
        environment:
          - NODE_ENV=production
        command: pnpm start


6. 本番デプロイ構成の補足 (Deployment Config)
------------------------------------------------------------------------
本番環境へデプロイする際は，上記 `Dockerfile` をマルチステージビルドに修正し，
軽量化を図ることが推奨される．

6-1. Dockerfile (本番用最適化例)
    ※ 必要に応じて `Dockerfile.prod` として作成する．

    FROM node:20-slim AS base
    ENV PNPM_HOME="/pnpm"
    ENV PATH="$PNPM_HOME:$PATH"
    RUN corepack enable
    COPY . /app
    WORKDIR /app

    FROM base AS prod-deps
    RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --prod --frozen-lockfile

    FROM base AS build
    RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
    RUN pnpm run build

    FROM base
    COPY --from=prod-deps /app/node_modules /app/node_modules
    COPY --from=build /app/apps/server/dist /app/apps/server/dist
    COPY --from=build /app/apps/client/dist /app/apps/client/dist
    
    EXPOSE 3000
    CMD [ "pnpm", "start" ]