# バッチ設計書 1-publish.ts

## 概要

本ドキュメントは、OpenCodeプロジェクトのリリースパブリッシュバッチ（publish.ts）の設計仕様を定義する。このバッチはパッケージのバージョン更新、npmへのパブリッシュ、GitHubリリースの公開を一括で実行する。

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

このバッチは、OpenCodeプロジェクトの新バージョンリリース時に実行される統合パブリッシュスクリプトである。複数のパッケージのバージョン番号を一括更新し、npm registryへのパブリッシュとGitHubリリースの公開を自動化する。

**業務上の目的・背景**：OpenCodeはCLI、SDK、プラグインなど複数のパッケージで構成されており、手動でのリリース作業は煩雑でエラーが発生しやすい。本バッチにより、バージョン番号の一貫性を保ちながら、全パッケージを確実にリリースできる。これにより開発者の作業負荷を軽減し、リリースプロセスの信頼性を向上させる。

**バッチの実行タイミング**：メインブランチ（ci/dev/beta）へのプッシュ時にGitHub Actionsワークフロー（publish.yml）から呼び出される。手動での実行も可能。

**主要な処理内容**：
1. プロジェクト内の全package.jsonファイルを検索し、バージョン番号を更新
2. Zed拡張機能のextension.tomlファイルのバージョン情報を更新
3. bun installを実行して依存関係を更新
4. SDK/JS用のビルドスクリプトを実行
5. リリースモードの場合、gitコミット・タグ作成・プッシュを実行
6. GitHubリリースのドラフト状態を解除
7. CLI、SDK、プラグインの各パブリッシュスクリプトを順次実行

**前後の処理との関連**：version.tsスクリプトが先行してGitHubリリースを作成し、changelog.tsがリリースノートを生成した後に本バッチが実行される。後続処理として、Tauri/Docker等のビルドが続く。

**影響範囲**：npm registry（opencode-ai、SDK、プラグインパッケージ）、GitHubリポジトリ（タグ、リリース）、Zed拡張機能リポジトリに影響を与える。

## バッチ種別

リリース自動化 / パッケージパブリッシュ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actions（ci/dev/betaブランチへのpush）、手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Script.version | リリースバージョン番号が設定されていること |
| Script.release | リリースモードフラグ（true/false） |
| Script.preview | プレビューモードフラグ（true/false） |
| GH_REPO | GitHubリポジトリ名が環境変数に設定されていること |
| npm認証 | npm registryへのパブリッシュ権限があること |
| GitHub認証 | gh CLIがリポジトリへの書き込み権限を持つこと |

### 実行可否判定

スクリプトは常に実行されるが、Script.releaseフラグがtrueの場合のみgitコミット・プッシュ・リリース公開が行われる。Script.previewがtrueの場合はコミット・プッシュがスキップされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Script.version | string | Yes | - | パブリッシュするバージョン番号 |
| Script.release | boolean | No | false | リリースモードフラグ |
| Script.preview | boolean | No | false | プレビューモードフラグ |
| Script.channel | string | No | - | リリースチャンネル（beta等） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| **/package.json | JSON | プロジェクト内の全package.jsonファイル |
| packages/extensions/zed/extension.toml | TOML | Zed拡張機能の設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| npm registry | パッケージ | opencode-ai、SDK、プラグインパッケージ |
| GitHub Releases | リリース | バージョンタグ付きリリース |
| git repository | コミット/タグ | バージョン更新コミットとタグ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各package.json、extension.toml（インプレース更新） |
| 出力先 | 元ファイルと同一パス |
| 文字コード | UTF-8 |
| 区切り文字 | JSON/TOML形式 |

## 処理フロー

### 処理シーケンス

```
1. package.jsonファイルの収集
   └─ Bun.Globで全package.jsonを検索（node_modules/dist除外）

2. バージョン番号の更新
   └─ 各package.jsonのversionフィールドを新バージョンに置換

3. Zed拡張機能設定の更新
   └─ extension.tomlのversion/releases URLを更新

4. 依存関係のインストール
   └─ bun installの実行

5. SDK/JSビルド
   └─ packages/sdk/js/script/build.tsの実行

6. リリース処理（Script.release=true時）
   └─ git commit, tag, push, gh release edit

7. CLIパブリッシュ
   └─ packages/opencode/script/publish.tsの実行

8. SDKパブリッシュ
   └─ packages/sdk/js/script/publish.tsの実行

9. プラグインパブリッシュ
   └─ packages/plugin/script/publish.tsの実行
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[package.jsonファイル収集]
    B --> C[バージョン番号一括更新]
    C --> D[extension.toml更新]
    D --> E[bun install]
    E --> F[SDK/JSビルド]
    F --> G{Script.release?}
    G -->|Yes| H{Script.preview?}
    G -->|No| L[CLIパブリッシュ]
    H -->|No| I[git commit/tag/push]
    H -->|Yes| J[スキップ]
    I --> K[gh release edit]
    J --> K
    K --> L
    L --> M[SDKパブリッシュ]
    M --> N[プラグインパブリッシュ]
    N --> O[バッチ終了]
```

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

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

本バッチはデータベース操作を行わない。ファイルシステムと外部サービス（npm/GitHub）への操作のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル操作エラー | package.json/tomlファイルの読み書き失敗 | ファイルパーミッション確認 |
| - | bun install失敗 | 依存関係解決エラー | bun.lockファイル確認、手動resolve |
| - | git操作失敗 | コミット/プッシュ失敗 | ブランチ状態確認、コンフリクト解決 |
| - | npm publish失敗 | 認証エラー/パッケージ重複 | npm認証確認、バージョン番号確認 |
| - | gh release edit失敗 | リリースが存在しない | version.tsの事前実行確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（即時失敗） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. バージョン更新後のエラー：git reset --hardで変更を取り消し、原因調査後に再実行
2. パブリッシュ途中のエラー：一部パッケージのみ公開された状態。未公開パッケージを個別にパブリッシュ
3. GitHubリリースエラー：gh CLIで手動でリリース状態を更新

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイル操作は個別） |
| コミットタイミング | 各ファイル更新直後 |
| ロールバック条件 | 自動ロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | package.json: 約10-20ファイル |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同時実行不可。GitHub Actionsの同時実行制御により、同一ワークフローの並列実行は防止される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | "=== publishing ===" |
| 進捗ログ | ファイル更新時 | "updated: {ファイルパス}" |
| セクションログ | 各パブリッシュ開始時 | "=== cli/sdk/plugin ===" |
| エラーログ | エラー発生時 | エラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー実行結果 | 失敗時 | GitHub Actions通知 |
| npm publish状態 | 失敗時 | GitHub Actions通知 |

## 備考

- highlightsTemplateはリリースノートのハイライト機能用テンプレートとして定義されているが、現在のコードでは使用されていない
- リリース後に5秒の待機時間（5_000ms）が設けられており、GitHubのリリース処理完了を待機している
- cherry-pick操作は.nothrow()でエラーを無視するよう設定されている
