# バッチ設計書 25-toolkit release-pkg windows

## 概要

本ドキュメントは、Nushellプロジェクトにおけるtoolkit release-pkg windowsコマンドの設計仕様を定義したものである。このバッチはWindows向けのリリースパッケージ（ZIPアーカイブおよびMSIインストーラー）を手動でビルドする。

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

toolkit release-pkg windowsは、Windows向けのNushellリリースパッケージを生成するツールである。aarch64とx86_64の両アーキテクチャに対して、標準配布用のZIPアーカイブとWinget配布用のMSIインストーラーを生成する。

**業務上の目的・背景**：Nushellの公式リリースはGitHub Actionsで自動化されているが、Wingetパッケージの検証失敗などでMSIの手動再生成が必要になることがある。このバッチにより、開発者がローカル環境でリリースパッケージを再生成し、Wingetリポジトリへの修正PR対応が可能となる。GitHub Actionsのワークフローを実行し直すことなく、迅速にパッケージを修正できる。

**バッチの実行タイミング**：リリース作業時、特にCI/CDでのパッケージ生成に問題が発生した場合に手動実行される。バージョンタグをチェックアウトした状態で実行する。

**主要な処理内容**：
1. 環境変数のクリア（RUSTFLAGS、CARGO_TARGET_DIR）
2. GitHub Actions互換の環境変数を設定
3. aarch64とx86_64の各ターゲットに対してループ処理
4. 各ターゲットでZIPアーカイブとMSIインストーラーを生成
5. 成果物をartifactsディレクトリにコピー

**前後の処理との関連**：.github/workflows/release-pkg.nuスクリプトを内部で呼び出す。Cargo.tomlからバージョン番号を取得する。

**影響範囲**：outputディレクトリ、target/wixディレクトリに中間ファイルが生成される。最終成果物はartifactsディレクトリに出力される。

## バッチ種別

リリースパッケージビルド / 配布物生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時のみ） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Windows環境 | Windows OSで実行されること |
| Visual Studio | MSVCクロスコンパイラがインストールされていること |
| ARM64ライブラリ | x86_64からビルドする場合、ARM64用コンパイラとライブラリが必要 |
| WiX Toolset 6.0以上 | dotnet tool install --global wix --version 6.0.0 |
| 7-Zip | ZIPアーカイブ作成用 |
| aria2c | 依存ファイルのダウンロード用 |
| Nushell環境 | Nushellがインストールされ、toolkitモジュールが利用可能であること |

### 実行可否判定

Windows環境で、必要なビルドツールがすべてインストールされている場合に実行可能。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --artifacts-dir | string | No | artifacts | 成果物の出力先ディレクトリ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Cargo.toml | TOML | バージョン番号の取得元 |
| .github/workflows/release-pkg.nu | Nushellスクリプト | 実際のビルド処理を実行 |
| Rustソースコード | Rust | ビルド対象のソースファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| {artifacts-dir}/ | ディレクトリ | 最終成果物の出力先 |
| output/ | ディレクトリ | 中間ファイル（ZIPアーカイブ生成時） |
| target/wix/ | ディレクトリ | MSIインストーラーの生成先 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ZIPファイル名 | nu-{version}-{arch}-pc-windows-msvc.zip |
| MSIファイル名 | nu-{version}-{arch}-pc-windows-msvc.msi |
| 出力先 | artifacts/（デフォルト） |
| アーキテクチャ | aarch64, x86_64 |

## 処理フロー

### 処理シーケンス

```
1. 環境変数のクリア
   └─ RUSTFLAGS、CARGO_TARGET_DIRを空にしてhide-env
2. GitHub Actions互換環境変数の設定
   └─ OS = "windows-latest"
   └─ GITHUB_WORKSPACE = カレントディレクトリ
   └─ GITHUB_OUTPUT = "./output/out.txt"
3. バージョン番号の取得
   └─ Cargo.tomlからpackage.versionを取得
4. artifactsディレクトリの作成
   └─ mkdir $artifacts_dir
5. 各アーキテクチャに対するループ処理
   └─ aarch64とx86_64の2つを処理
6. ZIPアーカイブの生成（各ターゲット）
   └─ outputディレクトリを削除
   └─ _EXTRA_=bin nu release-pkg.nuを実行
   └─ ZIPファイルをartifactsにコピー
7. MSIインストーラーの生成（各ターゲット）
   └─ outputディレクトリを削除
   └─ _EXTRA_=msi nu release-pkg.nuを実行
   └─ MSIファイルをartifactsにコピー
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[環境変数クリア]
    B --> C[GitHub Actions互換環境設定]
    C --> D[バージョン番号取得]
    D --> E[artifactsディレクトリ作成]
    E --> F{次のターゲットあり?}
    F -->|あり| G[TARGET環境変数設定]
    G --> H[outputディレクトリ削除]
    H --> I[ZIPアーカイブ生成]
    I --> J[ZIPをartifactsにコピー]
    J --> K[outputディレクトリ削除]
    K --> L[MSIインストーラー生成]
    L --> M[MSIをartifactsにコピー]
    M --> F
    F -->|なし| N[バッチ終了]
```

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

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ビルドエラー | Rustコンパイルエラー | ソースコードを修正 |
| - | クロスコンパイルエラー | ARM64/x64ライブラリ不足 | Visual Studioで必要なコンポーネントをインストール |
| - | WiXエラー | WiX Toolset未インストールまたはバージョン不一致 | dotnet tool install --global wix --version 6.0.0 |
| - | 7-Zipエラー | 7z.exeがPATHにない | 7-Zipをインストールしてパスを追加 |

### リトライ仕様

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

### 障害時対応

ビルドに失敗した場合は、エラーメッセージを確認し、不足している依存関係をインストールする。outputディレクトリを削除してから再実行する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 4パッケージ（2アーキテクチャ x 2形式） |
| 目標処理時間 | 数十分〜1時間程度 |
| メモリ使用量上限 | Cargoビルドに依存（通常数GB） |

## 排他制御

同一ディレクトリでの同時実行は不可。outputおよびtarget/wixディレクトリへの書き込みが競合する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| デバッグ情報 | バッチ開始時 | version, bin, os, target, src, distの値 |
| 進捗ログ | 各ステップ開始時 | "Packaging...", "Start building...", "Creating release archive..." |
| 成果物情報 | ファイル生成時 | "archive: --->" または "MSI archive: --->" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | 手動確認 |

## 備考

- 手動MSI生成手順（release-pkg.nuのコメントより）:
  1. リリースバージョンをチェックアウト（例: `git checkout 0.103.0`）
  2. CARGO_TARGET_DIRをクリア
  3. TARGET、GITHUB_WORKSPACE、GITHUB_OUTPUT、OS環境変数を設定
  4. 7z.exeとaria2c.exeをPATHに追加
  5. WiX 6.0をインストール
  6. release-pkg.nuを実行
- 生成されたMSIのハッシュ計算: `open wix\bin\x64\Release\nu-*.msi | hash sha256`
- Winget PRでハッシュ更新が必要な場合に使用
- lessコマンドのバイナリも同梱される（Windows版のみ）
