# 機能設計書 55-スタンドアロンCLI（@tailwindcss/standalone）

## 概要

本ドキュメントは、Node.jsのインストールなしで動作するスタンドアロンCLI `@tailwindcss/standalone` の機能設計を記述する。Bunでバンドルされ、各プラットフォーム向けバイナリとして配布される。

### 本機能の処理概要

**業務上の目的・背景**：Node.jsがインストールされていない環境や、CIパイプラインでのNode.js依存を避けたい場合、スタンドアロンバイナリとしてTailwind CSSのCLIを提供する必要がある。`@tailwindcss/standalone` は、Bunバンドラーを使用してTailwind CSSとその全依存関係を単一の実行可能バイナリにバンドルし、ダウンロードするだけで使用可能なCLIを提供する。

**機能の利用シーン**：Node.js不要な環境でTailwind CSSをビルドする場合に使用する。GitHub Releasesなどからプラットフォーム固有のバイナリをダウンロードし、直接実行する。

**主要な処理内容**：
1. グローバルモジュール解決フック（`__tw_resolve`）の設定 - Tailwind CSS関連モジュールをバンドル内で解決
2. グローバルモジュールロードフック（`__tw_load`）の設定 - プラグイン（forms、typography、aspect-ratio）のロード
3. Bun.plugin によるTailwind CSS API モジュールのバンドル
4. @tailwindcss/cli のエントリーポイントを import して実行

**関連システム・外部連携**：@tailwindcss/cli（CLIの本体）、Bun（バンドラー・ランタイム）、tailwindcss（コアライブラリ）、@tailwindcss/forms、@tailwindcss/typography、@tailwindcss/aspect-ratio（バンドルされるプラグイン）

**権限による制御**：特になし。バイナリの実行権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIツールのため関連画面なし |

## 機能種別

バンドル・パッケージング / CLI実行

## 入力仕様

### 入力パラメータ

@tailwindcss/cli と同一のCLIオプション（--input, --output, --watch, --minify, --optimize, --cwd, --map, --help）

### 入力データソース

@tailwindcss/cli と同一

## 出力仕様

### 出力データ

@tailwindcss/cli と同一

### 出力先

@tailwindcss/cli と同一

## 処理フロー

### 処理シーケンス

```
1. __tw_resolve グローバル関数の設定
   └─ Tailwind CSS関連モジュールIDをバンドル内ファイルに解決
2. __tw_load グローバル関数の設定
   └─ @tailwindcss/forms, typography, aspect-ratioプラグインのロード
3. __tw_version の設定
   └─ tailwindcssのpackage.jsonからバージョン情報を取得
4. Bun.pluginの登録
   └─ tailwindcss/* モジュールをバンドル済みオブジェクトとしてマッピング
5. @tailwindcss/cli の import と実行
   └─ CLIのindex.tsをそのまま実行
```

### フローチャート

```mermaid
flowchart TD
    A[スタンドアロンCLI起動] --> B[__tw_resolve設定]
    B --> C[__tw_load設定]
    C --> D[__tw_version設定]
    D --> E[Bun.plugin登録]
    E --> F[tailwindcss/* モジュールをバンドル済みオブジェクトにマッピング]
    F --> G[await import @tailwindcss/cli]
    G --> H[@tailwindcss/cliの通常処理実行]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-01 | モジュール解決フック | tailwindcss/*, @tailwindcss/* のモジュール参照をバンドル内のファイルに解決する | compile時のloadStylesheet/loadModule呼び出し時 |
| BR-55-02 | 組み込みプラグイン | @tailwindcss/forms, @tailwindcss/typography, @tailwindcss/aspect-ratio はバンドルに含まれ、require()で直接利用可能 | __tw_load呼び出し時 |
| BR-55-03 | CSSファイル解決 | index.css, theme.css, preflight.css, utilities.css はBunのファイルインポートで事前に解決される | __tw_resolve呼び出し時 |
| BR-55-04 | Bun埋め込みファイルパス検出 | baseDirが`/$bunfs/root`または`:/~BUN/root`を含む場合、Bun埋め込みファイルとして扱う | __tw_resolve呼び出し時 |
| BR-55-05 | バンドル済みAPIモジュール | tailwindcss, tailwindcss/colors, tailwindcss/plugin, tailwindcss/defaultTheme等のJSモジュールはBun.pluginで事前バンドル | importResolver呼び出し時 |

### 計算ロジック

特になし

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | モジュール解決エラー | バンドルに含まれないモジュールを@importしようとした場合 | __tw_resolveがfalseを返し、通常のモジュール解決にフォールバック |

### リトライ仕様

@tailwindcss/cli と同一

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

該当なし

## パフォーマンス要件

- Bunバンドラーにより全依存関係を単一ファイルにバンドルし、起動時のモジュール解決を高速化
- 主要プラグイン（forms, typography, aspect-ratio）を事前バンドルして即座に利用可能

## セキュリティ考慮事項

- バンドル内のモジュールのみを解決するため、外部からの任意モジュール注入リスクは低減
- globalThisへの関数登録（__tw_resolve, __tw_load）はバンドル内でのみ有効

## 備考

- ビルドスクリプトは `scripts/build.ts` にあり、Bunで実行される
- 対応プラットフォーム：darwin-arm64, darwin-x64, linux-arm64-glibc, linux-arm64-musl, linux-x64-glibc, linux-x64-musl, win32-x64
- Lightning CSSとParcel Watcherのネイティブバイナリもプラットフォーム別に含まれる
- detectLibcにより適切なネイティブバイナリが選択される

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.d.ts | `packages/@tailwindcss-standalone/src/types.d.ts` | グローバル型定義（__tw_resolve, __tw_load, __tw_version）を確認 |

**読解のコツ**: globalThisへの3つの関数/変数の追加が、スタンドアロンCLIの核心的なメカニズムである。これらは@tailwindcss/node/compile.tsのloadModule/loadStylesheet関数内で呼び出される。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@tailwindcss-standalone/src/index.ts` | スタンドアロンCLIのエントリーポイント全体（1-98行目） |

**主要処理フロー**:
1. **1-7行目**: CSSファイルのファイルインポート（Bun `with { type: 'file' }`構文）
2. **11-50行目**: `__tw_resolve` - モジュールID→バンドル内パスの解決ロジック
3. **51-61行目**: `__tw_load` - 組み込みプラグインのロード
4. **62行目**: `__tw_version` - バージョン情報設定
5. **66-96行目**: `Bun.plugin` - tailwindcss/* のJS APIをバンドル済みオブジェクトとしてマッピング
6. **98行目**: `await import('../../@tailwindcss-cli/src/index.ts')` - CLI本体の実行

#### Step 3: グローバルフックの利用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compile.ts | `packages/@tailwindcss-node/src/compile.ts` | resolveCssId（207-227行目）: __tw_resolve呼び出し箇所 |
| 3-2 | compile.ts | `packages/@tailwindcss-node/src/compile.ts` | resolveJsId（245-265行目）: __tw_resolve呼び出し箇所 |
| 3-3 | compile.ts | `packages/@tailwindcss-node/src/compile.ts` | importModule（181-195行目）: __tw_load呼び出し箇所 |

### プログラム呼び出し階層図

```
index.ts [スタンドアロンCLIエントリー]
    |
    +-- globalThis.__tw_resolve = (id, baseDir) => { ... }
    +-- globalThis.__tw_load = async (id) => { ... }
    +-- globalThis.__tw_version = packageJson.version
    |
    +-- Bun.plugin()
    |       +-- build.module('tailwindcss', ...)
    |       +-- build.module('tailwindcss/colors', ...)
    |       +-- build.module('tailwindcss/plugin', ...)
    |       +-- ... (その他のモジュール)
    |
    +-- await import('@tailwindcss-cli/src/index.ts')
            |
            +-- [@tailwindcss/cliの通常処理]
                    +-- compile() → loadStylesheet → __tw_resolve
                    +-- compile() → loadModule → __tw_load
```

### データフロー図

```
[入力]                      [処理]                                [出力]

モジュールID    ───▶  __tw_resolve(id, baseDir)  ───▶  バンドル内パス
(tailwindcss/*)                |
                               v
プラグインID    ───▶  __tw_load(id)              ───▶  プラグインモジュール
(@tailwindcss/*)               |
                               v
                     Bun.plugin(module mapping)  ───▶  バンドル済みexports
                               |
                               v
                     @tailwindcss/cli 実行       ───▶  ビルド済みCSS
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/@tailwindcss-standalone/src/index.ts` | ソース | スタンドアロンCLIのエントリーポイント |
| types.d.ts | `packages/@tailwindcss-standalone/src/types.d.ts` | ソース | グローバル型定義 |
| package.json | `packages/@tailwindcss-standalone/package.json` | 設定 | 依存関係・プラットフォームバイナリ定義 |
| index.ts | `packages/@tailwindcss-cli/src/index.ts` | ソース | CLI本体のエントリーポイント |
| compile.ts | `packages/@tailwindcss-node/src/compile.ts` | ソース | __tw_resolve, __tw_loadの呼び出し元 |
