CLI リリース管理スクリプト概要 (仮)

CLI リリース管理スクリプト仕様書

LismUI-Vue CLI (@lism-ui-vue/cli) は、Go でビルドされたバイナリを各 OS/Arch ごとに個別の NPM パッケージとして配信する構成をとっています。この複雑なリリースフローを安全かつ自動的に行うため、以下の 4 つのスクリプトが用意されています。

デプロイと実行の仕組み (アーキテクチャ)

この CLI は、ユーザーが npx @lism-ui-vue/cli を実行した際に、その環境に最適な Go バイナリを自動的に選択して実行する仕組みをとっています。

マルチプラットフォーム配信

NPM の optionalDependencies 機能を利用しています。

  1. メインパッケージ (@lism-ui-vue/cli): 実行用の JavaScript ラッパー (wrapper.js) のみを持ち、全プラットフォーム用のパッケージを依存関係として定義しています。

  2. OS別パッケージ (@lism-ui-vue/cli-windows-amd64 等): 各プラットフォーム専用の Go バイナリのみを含んだ軽量なパッケージです。

ユーザーがインストールする際、NPM は現在の OS/アーキテクチャに合致する OS別パッケージのみを自動的にダウンロードします。これにより、不要なバイナリ（Mac での実行時に Windows 用バイナリなど）をダウンロードせずに済みます。

実行時の詳細フロー

ユーザーがコマンドを入力してから Go バイナリが動くまでの、アダプター（JavaScript）を介した流れは以下の通りです：

  1. コマンド実行: ユーザーが npx @lism-ui-vue/cli や、インストール済みの lism-ui-vue コマンドを入力。

  2. アダプター (wrapper.js) の起動: package.json の bin 設定により、まずは JavaScript 実行環境（Node.js）で wrapper.js が起動します。

  3. OS/CPU の判別: wrapper.js が実行環境の OS と CPU アーキテクチャをチェックします。

  4. 適切なバイナリの特定: インストール済みの optionalDependencies（OS別パッケージ）の中から、現在の環境に一致する Go バイナリ（Windows なら .exe 等）のパスを特定します。

  5. プロセスの完全な引き継ぎ (重要): 特定された Go バイナリを Node.js の子プロセスとして実行します。ここでは単に起動するだけでなく、以下の「透明性」を確保しています：

    • 引数の移譲: ユーザーが入力したコマンド引数（例：init nuxt）を process.argv.slice(2) で抽出し、そのまま Go バイナリへ渡します。

    • 標準入出力の直結 (stdio: 'inherit'): JavaScript 側の stdin/stdout/stderr を Go バイナリと直結させています。これにより、Go 側で実装されている 対話型プロンプト (pterm) やカラー出力、進捗インジケーター が、ユーザーのターミナル上で直接、違和感なく動作します。

    • 終了コードの同期: Go バイナリが処理を終えて返した終了ステータス（Exit Code）を JavaScript 側でキャッチし、process.exit(status) で終了します。これにより、シェルスクリプトや CI ツールが、コマンドの成功・失敗を正しく検知できます。

  6. Go による高速処理: アダプターによるわずかなオーバーヘッド（ミリ秒単位）の後は、コンパイル済みの Go バイナリがネイティブスピードで実際の CLI 処理（ファイル生成やパッケージインストール等）を実行します。

スクリプト一覧と詳細

1. setup-oidc.js (初期設定用)

NPM の Trusted Publishing (OIDC) をセットアップするためのスクリプトです。

  • 仕組み:

    1. まだ NPM に存在しない新規パッケージ名を予約するため、中身が空のプレースホルダーパッケージを一度パブリッシュします。

    2. その後、GitHub Actions との信頼関係 (npm trust) を構築し、パスワードやトークンなしで GitHub から安全にデプロイできるように設定します。

  • 用途: 新しいバイナリパッケージ（例：新しい OS への対応）を追加した際の、初回のみ実行します。

2. sync-optional-dependencies.js (整合性維持用)

メインパッケージ (@lism-ui-vue/cli) の optionalDependencies に記載されているバイナリパッケージのバージョンを、現在の package.json のバージョンと一致させるスクリプトです。

  • 仕組み: メインのバージョン番号を読み取り、依存関係にある @lism-ui-vue/cli-*-* のバージョンをすべて同じ値に上書きします。

  • 実行タイミング: apps/cli/package.json の prepack フックに登録されており、npm publish 時に自動的に実行されます。

3. publish-npm.js (コア・自動化用)

GitHub Actions から全 7 つのパッケージ（バイナリ 6 種 + メイン 1 種）を一括でパブリッシュするためのメインエンジンです。

  • 仕組み:

    • dist/ 内のビルド済みバイナリを各サブパッケージディレクトリにコピーし、適切な package.json を生成します。

    • 高度なタグ管理: NPM の OIDC 要件を満たすため、現在の latest タグがプレリリース版（alpha等）であったり、まだ存在しない場合は、今回のリリースを自動的に latest として昇格させてパブリッシュします。

  • 用途: CI/CD 環境での自動リリース。

4. promote-to-latest.js (運用補助用)

既存のプレリリース版（例：0.1.1-alpha.x）を、手動で NPM の latest タグに紐付けるためのユーティリティです。

  • 仕組み: npm dist-tag add コマンドを全パッケージに対して一括実行します。

  • 用途: プレースホルダーとしてパブリッシュされた 0.0.1 を、最新のアルファ版などで上書きしたい場合に一度だけ使用します。

スクリプトの関係性とフロー

graph TD
    A[setup-oidc.js] -- "初回のみ" --> B((NPM レジストリ))
    C[sync-optional-dependencies.js] -- "自動同期" --> D[package.json]
    D --> E[publish-npm.js]
    E -- "一括デプロイ" --> B
    F[promote-to-latest.js] -- "タグ調整" --> B

  1. 初期化: setup-oidc.js で NPM 側の受け入れ態勢を整える。

  2. バージョン管理: 開発者がバージョンを上げると、sync-optional-dependencies.js が依存関係を整える。

  3. デプロイ: GitHub Actions が publish-npm.js を叩き、安全に全 OS 向けバイナリを配信する。

  4. メンテナンス: 必要に応じて promote-to-latest.js でタグの整理を行う。

これらのスクリプトをローカルで実行する場合は、適切な権限（npm login 済み）が必要です。