# CLAUDE.md — claude-code Helm Chart

> **共通ルール（要約）** — 詳細は `P:\Claude\CLAUDE.md`（全体共通）と `P:\Claude\HelmChart\CLAUDE.md`（Helm チャート共通: リリースフロー・ワークフロー・Gitea Secrets）を参照。
> 作業前に pull ／ 機能変更時は README 更新 ／ 作業単位ごとに commit → push まで ／ コミットに AI クレジットを付けない ／ pull で入った変更を revert しない ／ Helm はローカル実行不可（Python のみ可）。

## リポジトリ概要

Alpine Linux ベースの軽量コンテナで **Claude Code をリモート実行** するための Helm チャート。
ブラウザ（PC / スマートフォン）からアクセスし、**セッションごとに独立した使い捨て Pod** で
Git リポジトリ（GitHub / Gitea など互換 Git 全般）をチェックアウト・編集・検証・プッシュする。
一定時間アイドルなセッション Pod は自動破棄される。Raspberry Pi などの ARM ベアメタル運用を想定。

- **Gitea リポジトリ**: `ssh://git@192.168.9.65/helmchart/claude-code`
- **Helm リポジトリ**: `https://git.cafepieters.com/api/packages/helmchart/helm`
- **セッションイメージ**: `git.cafepieters.com/helmchart/claude-code/session:<appVersion>`（CI で publish）

> **注意**: セッション Pod は Gitea からリポジトリ単体を clone するため、`P:\Claude` の上位階層 CLAUDE.md は届かない。各リポジトリの CLAUDE.md 先頭に「共通ルール（要約）」を置く理由はこれ。

## アーキテクチャ（要点）

| コンポーネント | 実体 | 役割 |
|---|---|---|
| `gateway` | `nginxinc/nginx-unprivileged:alpine` | 単一入口。認証（token/basic/forward）、WebSocket リバースプロキシ、アクティビティ計測 |
| `manager` | `python:3.x-alpine`（標準ライブラリのみ） | セッション CRUD API、Web UI、アイドル/寿命回収ループ。in-cluster SA で K8s API を直接操作 |
| `session` | Alpine + node + git + ttyd + claude-code | セッションごとに作られる使い捨て Pod。`git clone` → `claude`（ttyd） → `claude-verify`/`claude-push` |
| `reaper` CronJob | `manager` イメージ `--reap-once` | manager 障害時の保険となる孤児掃除 |

- 制御プレーンはリリース NS、セッション Pod は専用 NS（`sessionsNamespace.name`）に分離。
- manager の RBAC はセッション NS の `pods` / `services` に限定した Role のみ（ClusterRole 不使用）。
- セッション Pod は **API サーバー到達不可**（`automountServiceAccountToken: false`）、
  非 root / `readOnlyRootFilesystem` / drop ALL caps / seccomp RuntimeDefault、
  egress は DNS + git ホスト + `api.anthropic.com` のみ（NetworkPolicy）。
- ファイル実体は `files/`（`.Files.Get` で ConfigMap 化）: `manager.py` / `session-entrypoint.sh`
  / `gateway.conf.template` / `gateway-entrypoint.sh` / `Dockerfile.session`。

## README 更新時の追加事項

- values の新設キー、挙動変更、セキュリティ影響は README の該当セクションと values リファレンス表へ反映する。
- 手動リリース（`-a` 等）時は対応する `CHANGELOG-<version>.md` を追加し、README の「バージョン履歴」にも 1 行追加する（このリポジトリの慣行）。

## リリースフロー（組織ルールとの差分）

- **バージョン番号**: `Chart.yaml` の `version` / `appVersion` は
  **主アプリ = Claude Code CLI（`@anthropic-ai/claude-code` の npm 最新版）と同一**にする。
- **ワークフロー（3 本）**
  - `helm-release.yaml` — `main` への push で発火。`helm lint` の後、`Chart.yaml` の version が
    未リリース（Gitea リリース・Package Registry 双方に存在しない）なら タグ + Gitea リリース +
    チャート publish。リリース済みなら lint のみで終了（再 publish しない）。
  - `image-update-and-release.yaml` — 毎週月曜 3:00 JST。npm の Claude Code 最新版と
    base image（nginx / python）の最新 Alpine タグを確認。Claude Code 更新時は
    `values.yaml` / `Chart.yaml` / README 履歴を更新しコミット → タグ + リリース + publish。
    base image のみ更新時は `values.yaml` を更新してコミットのみ（**リリースなし**）。
  - `session-image.yaml` — `files/Dockerfile.session` 等の変更、または上記による `Chart.yaml`
    更新で発火。セッションイメージを `linux/amd64,linux/arm64` でビルドして
    Gitea Container Registry（`helmchart/claude-code/session:<appVersion>` + `latest`）へ push。
- **手動リリース（臨時）**: 例 `2.1.259` → `2.1.259-a` → `2.1.259-b`。

## 改修履歴

### 初版（2026-09-03, v2.1.259）

チャート新規作成。gateway + manager + 使い捨て session Pod + reaper CronJob の構成で、
ブラウザからの Claude Code リモート実行、GitHub/Gitea 両対応、アイドル自動破棄、
NetworkPolicy / RBAC 最小化 / restricted PodSecurity を実装。

**対象ファイル**: 全ファイル（初期コミット）