# バッチ設計書 7-ghostty-tip

## 概要

本ドキュメントは、指定したコミットSHAに対応するtipリリースが存在するか確認するNuスクリプト `ghostty-tip` の設計仕様を記載する。

### 本バッチの処理概要

本バッチは、特定のGitコミットに対応するGhosttyのTip（Nightly）リリースがCloudflare R2ストレージに存在するかを確認するスクリプトである。

**業務上の目的・背景**：GhosttyのCI/CDパイプラインでは、mainブランチへのマージ時にTip（Nightly）リリースが自動的にビルド・アップロードされる。release-tip.ymlワークフローでは、重複ビルドを防ぐため、同じコミットに対するTipリリースが既に存在するかをチェックする必要がある。本スクリプトは、Tipリリースのストレージ（tip.files.ghostty.org）に対してHTTP HEADリクエストを送信し、該当コミットのリリースファイルが存在するかを確認する。

**バッチの実行タイミング**：release-tip.ymlワークフローのsetupジョブで実行

**主要な処理内容**：
1. コミットSHAを引数として受け取る
2. Tipリリースの期待されるURLを構築
3. HTTP HEADリクエストでファイルの存在確認
4. 存在有無に応じて終了コードを返す

**前後の処理との関連**：release-tip.ymlワークフローのsetupジョブで呼び出され、should_skip出力の判定に使用される。リリースが存在する場合、後続のビルドジョブをスキップする。

**影響範囲**：CI/CDワークフローの実行判断に影響を与える

## バッチ種別

存在確認 / CI/CD制御

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（CIトリガー） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | release-tip.ymlワークフロー |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| nu | Nushellがインストールされていること |
| ネットワーク | tip.files.ghostty.orgへのHTTP接続が可能であること |

### 実行可否判定

- コミットSHA引数が指定されていること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| commit | string | Yes | なし | フルレングスのコミットSHA（40文字） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| tip.files.ghostty.org | HTTP | Tipリリースのストレージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準エラー | テキスト | リリースが存在しない場合のエラーメッセージ |
| 終了コード | 整数 | 0=存在、1=不存在 |

### 出力ファイル仕様

本バッチはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. コミットSHA取得
   └─ 引数からコミットSHAを取得
2. URL構築
   └─ https://tip.files.ghostty.org/{commit}/ghostty-macos-universal.zip
3. HTTP HEAD リクエスト
   └─ http head でURLの存在確認
4. 結果判定
   └─ 成功（200 OK）: exit 0
   └─ 失敗（404等）: エラーメッセージ出力、exit 1
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[コミットSHA取得]
    B --> C[URL構築]
    C --> D[HTTP HEAD リクエスト]
    D --> E{レスポンス成功?}
    E -->|成功| F[exit 0]
    E -->|失敗| G[エラーメッセージ出力]
    G --> H[exit 1]
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | リリース不存在 | 指定コミットのTipリリースがない | 正常動作（後続でビルドを実行） |
| 1 | ネットワークエラー | ストレージへの接続失敗 | ネットワーク接続を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. ネットワーク接続を確認
2. tip.files.ghostty.org のサービス状態を確認
3. コミットSHAが正しい形式か確認

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1リクエスト |
| 目標処理時間 | 5秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

特になし。読み取り専用の確認処理。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | - |
| 進捗ログ | なし | - |
| 終了ログ | なし | - |
| エラーログ | リリース不存在時 | "The SHA {commit} does not have a corresponding tip release." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし | - | - |

## 備考

### Nushellについて
- 本スクリプトはNushell（nu）で記述されている
- `#!/usr/bin/env nu` シェバンでNushellインタープリタを指定
- `http head` コマンドはNushellのビルトインコマンド

### コメント形式
- Nushellのコメントは `#` で始まる
- 関数定義は `def main [param: type] { ... }` 形式

### 確認対象URL
- `https://tip.files.ghostty.org/{commit}/ghostty-macos-universal.zip`
- macOS Universal バイナリの存在を確認（代表的なアーティファクト）

### 使用例
```bash
# Tipリリースが存在する場合
nix develop -c nu .github/scripts/ghostty-tip abc123...
# 終了コード: 0

# Tipリリースが存在しない場合
nix develop -c nu .github/scripts/ghostty-tip xyz789...
# 出力: The SHA xyz789... does not have a corresponding tip release.
# 終了コード: 1
```
