開発手順

開発環境の構築手順

必要環境

• LinuxまたはmacOS
• Docker / Docker Compose
• uv
• Node.js

セットアップ手順

すべてのmakeコマンドはプロジェクトルートから実行する （app/へ移動して実行すると${PWD}がずれてMakefile内のパス解決が誤動作する）。

1. 本リポジトリをclone

2. .env-exampleを.envにコピーして環境変数を設定

   cp .env-example .env

   COMPOSE_PROFILE・DATA_DIR・UID・GIDを環境に合わせて編集する

3. 開発環境のセットアップを実行

   make setup

4. 起動

   make deploy

開発コマンド

コマンド	内容
make format	整形 + 軽量lint + 自動修正
make test	全チェック実行（コミット前の必須検証）
make test-e2e	e2eテスト（Playwright）単独実行
make update	依存更新

e2eテスト（make test-e2e）は開発環境（make deploy）が起動している必要がある。

依存更新後の追随作業

make updateはpnpm update --latestによりpackage.jsonの指定範囲を超えて更新する。 実行後は次の2点を確認する。

TypeScriptの版を6系に留める。 typescript-eslintがTypeScript 7を未サポートであり、 svelte-checkもTypeScript 7では6系との併存インストールと専用フラグを要求するためである。 7系へ上がった場合はpnpm add -D 'typescript@^6.0.3'で戻す。 両ツールがTypeScript 7へ対応した時点で本運用を解除する。 対応状況は次の2点で判定する。

• typescript-eslint: 対応issue（https://github.com/typescript-eslint/typescript-eslint/issues/10940）がcloseされていること
• svelte-check: node_modules/svelte-check/bin/ts-version-check.jsがTypeScript 7の単独構成で例外を送出しないこと

Playwrightのイメージ版を揃える。 @playwright/testが更新された場合は、compose.yamlのplaywrightサービスが指す mcr.microsoft.com/playwrightのタグを同じ版へ更新する。 イメージ同梱のブラウザバイナリはパッケージの版ごとに配置が変わるため、 一致しないとmake test-e2eがブラウザ起動時に失敗する。

サプライチェーン攻撃対策

npm / PyPIレジストリへの悪意あるパッケージ公開に対し、次の方針を採用する。

• npmパッケージ: pnpm-workspace.yamlのminimumReleaseAge: 1440で公開から1日未満のインストールを禁止する
• PyPIパッケージ: pyproject.tomlの[tool.uv]節exclude-newer = "1 day"で公開から1日未満のインストールを禁止する
• pnpm installは--frozen-lockfileを明示してロックファイル乖離時の再resolveを禁止する
• GitHub Actionsのuses:はコミットSHAとバージョンコメントで固定する（.github/workflows/配下全ファイル）

依存更新はmake updateを使う。

推移的依存（直接インストールしていない依存の依存）の脆弱性は、上記の自動更新対策だけでは解消されない場合がある。 脆弱性はDependabotアラートと.github/workflows/audit.yamlの定期監査で検知し、 pnpm-workspace.yamlのoverridesで安全なバージョンへ引き上げて対処する。

GitHubリポジトリ設定のDependabot security updates（自動修正PRの作成）は無効にしている。 Dependabotのアップデーターが本リポジトリのpnpmロックファイル環境では推移的依存を 安全なバージョンへ引き上げられず、自動修正の試行が繰り返しsecurity_update_not_possibleで 失敗していたためである。

Docker構成

サービス構成・環境変数はcompose.yaml / .envを参照。 プロファイルはproduction（既定推奨）とdevelopmentの2種類がある。

DBマイグレーション運用

自動適用

make deploy（docker compose up）の起動時にマイグレーションが自動適用される。 稼働中のappを止めずに即座にマイグレーションを反映したい場合はmake migrateを実行する。

マイグレーションファイルの追加

新規スキーマ変更は必ずpnpm run db:generate経由で生成する。 drizzle/migrations/meta/_journal.jsonのwhen値（UNIXミリ秒）は直前エントリより大きくなければならない。 別ブランチで生成したmigrationのmergeで順序が逆転する場合は、新しい側のwhenを再生成してからcommitする。

既存行の値の読み替え・初期値の設定が必要な場合は、生成されたマイグレーションファイルへ値変換のSQLを書き足す。 pnpm run db:generateはスキーマ定義の差分からDDLのみを生成し、既存行の値をどう埋めるかを表現できないためである。 先例として0003_sort_order_and_status.sql（既存カラムの廃止に伴う値の読み替え）・0004_add_timer_expired.sql（新設カラムへの初期値の設定）が手書きの変換SQLを含む。

履歴整合のリカバリー

DBが半端な状態になった場合はmake sqlから__drizzle_migrationsテーブルと実DB状態を整合させる。 整合手順を実行する前に必ずmake backupを取得する。

典型例として、make start時にmigrate-devがexit 1で失敗し ALTER TABLE ... ADD ... Duplicate column nameが出る場合がある。 drizzle-kit pushでスキーマを先行適用すると実スキーマは最新だが __drizzle_migrationsに当該マイグレーションが記録されず、再適用で重複エラーになる。 実スキーマが当該マイグレーション到達済みであることを確認したうえで、 __drizzle_migrationsへ記録行を1行挿入して整合させる。 hashは当該マイグレーションSQLファイル全文のsha256、created_atは drizzle/migrations/meta/_journal.jsonの当該エントリのwhen値を用いる。

CI/CD

masterへのpushおよびPR時にci.yamlが自動実行される（.github/workflows/ci.yaml参照）。 masterへのpushでdocs/配下に変更があればdocs.yamlワークフローが自動実行され、 GitHub Pagesへデプロイされる。 依存の脆弱性監査はaudit.yamlが毎日06:00 UTC（JST 15:00）に定期実行し、 検出結果をGitHub Code Scanningへアップロードする（.github/workflows/audit.yaml参照）。

ドキュメントサイト運用

make docs

http://localhost:5173/GLATasks/でプレビューできる。

バックアップとリストア

バックアップ

make backup

バックアップ先: ${DATA_DIR}/backups/YYYYMMDD_HHMMSS/（DBダンプ + キーファイル）。 既定で直近5世代を保持する（BACKUP_KEEP環境変数で変更可能）。 DBコンテナが停止中の場合はエラー終了する。初回デプロイなどDBがない状態ではSKIP_DB_DUMP=1でスキップ可能。

リストア

${DATA_DIR}/backups/YYYYMMDD_HHMMSS/配下のSQLとキーファイルをDBコンテナへリストア後、 make restart-appを実行する。

リリース手順

事前にghコマンドをインストールしてgh auth loginでログインしておく。次のいずれかを実行。

gh workflow run release.yaml --field="bump=PATCH"
gh workflow run release.yaml --field="bump=MINOR"
gh workflow run release.yaml --field="bump=MAJOR"

進捗はhttps://github.com/ak110/GLATasks/actionsで確認できる。