二次開発

本番ソースは 3 か所に分かれています。プライベートの Agent/Worker リポジトリ、プライベートの Frontend リポジトリ、サニタイズ済みの公開リポジトリです。公開リポジトリはサニタイザースクリプトで一方通行に生成されます。本番ロジックはそこで編集しないでください。

Worker と Frontend

node --test tests/*.test.mjs
node --check app.js
node --check js/admin.js

リリース前の完全検証：

bash test.sh
pnpm run build
pnpm test
pnpm run test:update
pnpm exec wrangler deploy --dry-run --outdir .wrangler-dry-run

pnpm run build は Worker Static Assets を準備します。古い Frontend のコピーをビルドディレクトリにコピーしないでください。デプロイ前に、dry-run が期待どおりの D1・R2・Durable Object・Assets・Cron バインディングを列挙していることを確認します。

Rust Agent

安定版 Rust ツールチェーンが必要です。クロスアーキテクチャの Linux リリースには、プロジェクトの Zig/target セットアップも必要です。最低限のチェック：

cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

ローカルで動くだけではリリースできません。Agent リリースはサポートする全アーキテクチャの静的 Linux ELF バイナリを生成し、VERSION と SHA256SUMS を更新し、インストーラの段階的ハッシュチェーンを検証する必要があります。

設定とシークレット

公開設定とシークレットは分けて扱います。

• ADMIN_USERNAME・ADMIN_PASSWORD・ADMIN_PATH は初回デプロイに必須です。
• ログイン後、管理者は短命の x-admin-session を使用します。パスワードを保持・再生しないでください。
• Agent と遅延ノードはノード単位の scoped Token を使い、公開 API には一切現れません。
• DEVELOPER_API_ORIGINS は /api/v1 のブラウザ読み取りのみを制御します。
• NQ 画像ホストの URL とトークンは Worker Secret のみです。D1 設定・通常バックアップ・フロントエンドには入りません。
• カスタム URL は資格情報なしの HTTPS であり、サーバー側のプライベート・リダイレクト検査に合格する必要があります。

開発には別の Cloudflare リソースとテスト資格情報を使います。ローカルプレビューを本番管理 API に向けず、URL の ?api= パラメータで任意の API ベースを受け入れないでください。

公開 API の変更

/api/v1 は安定互換ラインです。

1. 任意フィールドと新しいエンドポイント機能の追加は可能。
2. v1 内では既存フィールドを黙って削除・リネーム・再意味付けできない。
3. 新しいクエリパラメータにはデフォルト・範囲制限・正規化されたキャッシュキーが必要。
4. 履歴エンドポイントには上限が必要。0 や負の値は「無制限」を意味しない。
5. 公開出力は IP・ポート・URL 資格情報・内部エラーをサニタイズする。
6. ブラウザ CORS は許可リストの正確なオリジンのみを返す。
7. マニフェスト・エンドポイントドキュメント・契約テスト・代替フロントエンドの例を更新する。

クライアントは worker_version から推測せず、/api/v1 マニフェストで機能を検出してください。

フロントエンドのルール

• 公開状態と Agent オンライン状態は別ソースです。1 つの真偽値にまとめない。
• lite=1 は初回描画を提供し、チャートは詳細を開いたときに読み込む。
• エラー・空データ・warnings[] は別々に描画する。
• API テキストは textContent または統一エスケープヘルパーで描画する。
• 320・375・390・768・1280・1440 px でページ全体の横方向オーバーフローがないことを確認する。
• モーダルにはフォーカストラップ・Escape で閉じる・背景スクロールロック・オープナーへのフォーカス復帰が必要。
• 静的アセット変更時はコンテンツキャッシュキーを上げ、テストで現在のエントリキーを固定する。

Agent のルール

• root ディスク容量はシステムボリュームであり、マウントの合計ではありません。Linux IO はパーティション・LVM・物理デバイス間の二重計上を防ぐため、一貫した単一の計上レベルを使います。
• オフラインキューの書き込みは制限付き権限・原子的置換・fsync を使い、失敗時は dirty を維持します。
• アップロード ACK・終了・更新再起動の前にフラッシュします。
• 入力メトリクスには型・範囲・時間ウィンドウの検証が必要です。
• インストール・更新・ロールバックはバイナリの所有者・実行権限・SHA-256 チェーンを維持します。
• 固定の NQ/IP アクションはコンパイル済みアクション enum のみ受け付けます。任意のコマンド・URL・引数・スケジュールに拡張しないでください。

バージョニングとリリース

アプリ・Worker・ドキュメント・Agent は同じ数値バージョンを共有します。安定版は十進で増えます：パッチ 1.1.93、次のマイナー 1.2.0。1.0.99 への繰り上がりはしません。

App/Worker/docs: 1.1.93
Agent: v1.1.93
App ソースタグ: app-v1.1.93
Agent タグ/リリース: v1.1.93

同じバージョンの公開済みバイナリを上書きせず、公開タグも動かさないでください。リリースレベルの変更前にバージョンを上げ、テスト・ビルド・チェックサム生成・リリースアセット作成をローカルで行います。ドキュメントのみの修正は製品バージョンを維持できますが、ランタイムは不変である旨を明記してください。

公開リポジトリはセルフホスター向けの唯一のソーススナップショット・更新マニフェスト・リリース配布入口です。プライベートの Agent/Worker と Frontend リポジトリが本番ソースで、サニタイザーで一方通行にエクスポートされます。公開ワンクリックビルドは update-manifest.json で固定されたリリースをダウンロードし、本番 Agent はデプロイ済みサイトの /bin からインストール・更新し、GitHub API を直接参照しません。

リリースとデプロイの流れ

1. ローカルゲート：bash test.sh で Worker・フロントエンド・インストーラーマニフェストの全テストを実行し、agent/build-release.sh で 7 アーキテクチャのバイナリと bin/VERSION・bin/SHA256SUMS を生成します。
2. ハッシュチェーン：新しいダイジェストを setup.sh/update.sh（SHA256SUMS_SHA256）→ install.sh/quick-install.sh（DEFAULT_SETUP_SHA256）→ マニフェストテストと管理画面のインストールコマンドテンプレートの順に反映します。
3. リリース：プライベート Agent リポジトリをコミット・プッシュし、タグ vX.Y.Z と GitHub Release（7 アセット）を作成 → フロントエンドリポジトリをコミット・タグ付け → 公開リポジトリへ一方向エクスポートし、vX.Y.Z/app-vX.Y.Z タグと Release アセットを公開リポジトリへミラー（ワンクリックデプロイとオンライン更新が依存）→ worker/deploy.sh でデプロイ → scripts/smoke-prod.mjs で本番確認。
4. セルフホスト更新：ワンクリックデプロイでは NIE-SLA Online Update ワークフローが 6 時間ごとに安定版を確認します。すぐ更新する場合はデプロイリポジトリの Actions タブで Run workflow を実行してください。更新が止まっている場合は FAQ「管理画面に新バージョンが出ているのに更新されない」 を参照；Actions を使わない場合はリポジトリを同期して npm run deploy を実行します。

コミット前チェックリスト

• 作業ツリーに範囲内のファイルだけが含まれる。
• テスト・フォーマット・lint・依存関係監査・本番ビルドが通る。
• Worker の変更が Wrangler dry-run に通る。
• Frontend がデスクトップ・モバイルのページチェックに通る。
• 公開エクスポートがシークレットスキャンに通り、プライベートソースから一方通行で生成される。
• バージョン・マニフェスト・タグ計画・Agent の VERSION・ドキュメントが一致する。
• 開発ログ・キャッシュ・ビルド一時ディレクトリ・シークレットをコミットしない。

代替フロントエンドだけなら Worker のフルフォークは不要です。API 連携を参照してください。見た目だけの変更はテーマを使います。