# CLAUDE.md — secret-manager Helm Chart

## リポジトリ概要

クラスター内の複数プロジェクトで横断的に使う「認証情報」を 1 つの Helm チャートで
一元管理する。外部メールの SMTP/IMAP 設定・API キー・汎用資格情報を定義し、
指定した複数ネームスペースへ同一の Kubernetes Secret として配布する。

**設計目標**: 認証情報の変更が発生したら、このチャートの values を更新して
`helm upgrade` するだけで、クラスター上の全プロジェクトに反映される。

- **Gitea リポジトリ**: `ssh://git@192.168.9.65/helmchart/secret-manager`
- **Helm リポジトリ**: `https://git.cafepieters.com/api/packages/helmchart/helm`

## 作業ルール（必読）

1. **機能を追加・変更したら、必ず `README.md` を更新してから作業完了とする。**
   - 追加・変更した機能・パラメータ・挙動を README.md に反映する。
2. **変更は必ず Git Commit / Push すること。**
   - 作業単位ごとにコミットし、`origin(main)` へ push するまでが作業完了。
3. **コミットメッセージに Claude クレジット（`Co-Authored-By` 等）を追記することは禁止。**
   - `user.name = Claude` でコミットされるため、ユーザー名で判別可能。
4. `git pull` で取り込まれた変更は常に尊重する。revert して push することは禁止。
   不適切に見える場合はユーザーに改善提案を提示し、承認を得てから対応する。

## バージョン方針

- このチャートには「主アプリ」となる外部プロダクトが存在しない（チャート自身がアプリ）。
  そのため `Chart.yaml` の `version` / `appVersion` は **チャート独自に SemVer で採番**する。
  （他チャートの「主アプリのバージョンと同一」ルールは適用対象外）
- 破壊的変更 = メジャー、機能追加 = マイナー、修正 = パッチ。

## リリースフロー

新バージョンを出す手順は「`Chart.yaml` の `version` / `appVersion` を上げて `main` に push」だけ。
以降は CI が処理する。

### `.gitea/workflows/helm-release.yaml`（push トリガ）
- `main` への push（`Chart.yaml` / `values.yaml` / `values.schema.json` / `templates/**` 変更時）
  および手動実行で発火。
- `helm lint --strict` → **現在の `version` が Package Registry に未公開のときだけ**
  リリースする（`helm search repo --version` で存在確認）。
- 他リポジトリの「毎 push で無条件公開」する共通版とは意図的に異なる。README・examples
  だけの変更で push してもリリースは発生しない。
- リリース内容 = Package Registry 発行 + Git タグ `v<version>` + Gitea リリース（`.tgz` 添付）。
  タグ・リリースは既存なら skip（冪等）。

### `.gitea/workflows/image-update-and-release.yaml`（週次）
- 毎週月曜 03:00 UTC（JST 12:00）+ 手動実行。
- **上流イメージの自動追従はしない**（このチャートは Secret を生成するだけで
  追従対象イメージが無い）。バージョンは常に手動で `Chart.yaml` を更新する。
- 役割は「push 側の取りこぼし対策」— `version` が未公開なら週次でリリースを実行する。
- 将来サブチャート等の追従対象が増えたときの追加ポイントは同ファイル内にコメントで用意済み。

### 手動リリース（臨時）
- 改修作業で臨時リリースが必要なら `version` 末尾にアルファベットを付与（例: `0.2.0` → `0.2.0-a`）。

## 必要な Gitea Secrets

| シークレット名 | 用途 |
|---|---|
| `GITEA_TOKEN` | Gitea API（リリース作成・タグ操作） |
| `REGISTRY_USER` | Gitea Package Registry ユーザー名 |
| `REGISTRY_TOKEN` | Gitea Package Registry トークン |

## Git Configuration (local)

| 項目 | 値 |
|---|---|
| user.name | Claude |
| user.email | claude@cafepieters.com |
| core.sshCommand | `ssh -i P:/Claude/.ssh/id_claude -o StrictHostKeyChecking=no` |

## 実行環境

- **Helm はローカル未インストール**。テンプレートのレンダリング確認は CI（`helm lint`）に依存する。
  ローカルでは YAML 構文・Go テンプレート構文を目視で慎重に確認すること。
- OS: Windows 11 Pro

## アーキテクチャ要点

- `templates/_helpers.tpl` の `secret-manager.secret` が中核。
  1 論理 Secret を受け取り、実効ネームスペースごとに複製した Secret マニフェストを出力する。
- 配布先の決定順:
  1. エントリの `namespacesOverride`（非空ならそれを使用）
  2. `distribution.reflector.enabled` が true → リリース先ネームスペースのみに作成し reflector アノテーション付与
  3. それ以外 → `distribution.namespaces` (+ `includeReleaseNamespace`) を重複排除した一覧
- Helm はリリースマニフェストに含まれる別ネームスペースの Secret も追跡するため、
  `namespaces` からネームスペースを外して `helm upgrade` するとそのコピーは削除される。
- 資格情報は `stringData` で書き込む（テンプレート側で全値を文字列へ強制）。

## チャート改修履歴

### 自動更新・リリースワークフローの整備（2026-09-03, v0.1.0）

`.gitea/workflows/` を 2 本体制に。`helm-release.yaml` を「無条件公開」から
「未公開バージョンのみリリース」に変更（`helm search repo --version` で存在確認し、
未公開時のみ Package Registry 発行 + Git タグ + Gitea リリース）。`paths` フィルタで
`Chart.yaml`/`values.yaml`/`values.schema.json`/`templates/**` の変更時のみ発火。
`image-update-and-release.yaml` を新設（週次）。上流イメージが無いチャートのため
バージョン自動採番はせず、push 側の取りこぼし対策（未公開バージョンの週次リリース）
として動作。将来の追従対象追加用コメントブロックを同梱。

**対象ファイル**: `.gitea/workflows/helm-release.yaml`,
`.gitea/workflows/image-update-and-release.yaml`, `README.md`, `CLAUDE.md`

### 初版設計・実装（2026-08-31, v0.1.0）

空リポジトリから初期実装。`distribution`（namespaces 複製 / reflector / reloader）、
`common`（namePrefix・labels・annotations・immutable）、`mail.providers`（SMTP/IMAP/POP3 +
`smtp.env` + 任意の `msmtprc`）、`api.credentials`、`generic.secrets`（任意 type）を実装。
`values.schema.json`、`examples/`、`.gitea/workflows/helm-release.yaml` を追加。

**対象ファイル**: `Chart.yaml`, `values.yaml`, `values.schema.json`, `templates/*`,
`examples/*`, `.gitea/workflows/helm-release.yaml`, `README.md`, `.gitignore`, `CLAUDE.md`