# Taida パッケージ

> **[PHILOSOPHY.md](/_corpus/PHILOSOPHY.md) -- I.** 深く考えずに適当にぶちこんでけ

Taida のパッケージシステムは `packages.tdm` マニフェストと `>>>` / `<<<` 演算子で構成されます。バージョン管理、依存解決、ロックファイルを備えた完全なパッケージマネージャです。

---

## packages.tdm マニフェスト

プロジェクトルートに `packages.tdm` を配置します。`taida init` で雛形を生成できます。

```taida
// packages.tdm

// Dependencies with version pins
>>> author/some-lib@a.3
>>> another/tool@b.12

// Exports (what this package provides)
<<<@a.1 @(myFunction, MyType, helper)
```

### マニフェスト構造

| セクション | 構文 | 用途 |
|------------|------|------|
| 依存関係 | `>>> author/pkg@gen.num[.label]` | バージョン付きパッケージ依存の宣言 |
| エクスポート | `<<<@gen.num[.label] @(symbols)` | パッケージバージョンと公開 API の宣言 |

### バージョン形式: `@gen.num[.label]`

Taida は SemVer を使いません。`@gen.num` 形式を採用しています:

```taida
>>> author/package@a.3         // exact: 世代 a の publish #3
>>> author/package@b           // 世代指定: 世代 b の最新を lockfile が解決
>>> author/package@a.4.alpha   // ラベル付き: プレリリース版
```

| フィールド | 意味 | 例 |
|-----------|------|-----|
| **gen** | 世代。破壊的変更時に `taida verify` が自動インクリメント | `a`, `b`, `aa` |
| **num** | パッケージの通算 publish 回数（リセットなし） | `1`, `47`, `128` |
| **label** | 任意のラベル（省略可）。プレリリースやリリース候補の識別 | `alpha`, `rc-1`, `beta2` |

`@c.47` を見れば:
- 破壊的変更が **2 回** あった（世代 c）
- 通算 **47 回目** の publish

### ラベル

ラベルはバージョンの末尾に `.label` として付与します。`taida publish --label <LABEL>` で指定します。

```taida
<<<@a.4.alpha @(run, Config)    // プレリリース版
<<<@a.5.rc-1 @(run, Config)     // リリース候補
<<<@a.6 @(run, Config)          // 正式リリース
```

ラベルの命名規則: `[a-z0-9][a-z0-9-]*`（小文字英数字で始まり、末尾ハイフン不可）

### 世代

世代の進行: `a → b → c → ... → z → aa → ab → ...`

世代は `taida publish` 時に verify が自動判定します。開発者が手動で指定することはありません。

---

## インポート / エクスポート

### パッケージからのインポート

```taida
// External package (version resolved from packages.tdm or inline)
>>> author/package@a.3 => @(funcA, funcB)

// Local file
>>> ./utils.td => @(helper, format)

// With alias
>>> ./math.td => @(add, subtract => sub)
```

### シンボルのエクスポート

```taida
// Multiple symbols
<<< @(add, subtract, Point)

// Single symbol
<<< myFunction

// One-liner export
<<< double x: Int = x * 2 => :Int
```

---

## taida-community レジストリ

Taida パッケージは [taida-community](https://github.com/taida-community) GitHub organization でホストされます。Fork ベースのレジストリです。

### 仕組み

1. **初回公開**: `taida publish` が `taida-community/proposals` に Issue を自動作成し、審査を受ける
2. **審査**: 自動 CI + ゲートキーパーレビュー
3. **承認**: `taida-community/{package-name}` に Fork リポジトリが作成される
4. **更新**: 以降のバージョンは Fork リポジトリへの PR として自動作成される

### パッケージ命名規則

```
author/package-name
```

- `author`: GitHub ユーザー名または org 名
- `package-name`: 小文字、ハイフン区切り

---

## CLI コマンド

### `taida init`

`packages.tdm` テンプレート付きの新規プロジェクトを生成します:

```bash
taida init
```

生成されるファイル:

```
my-project/
  packages.tdm
  main.td
  .taida/
    taida.lock
```

### `taida install`

`packages.tdm` に宣言された全ての依存パッケージをインストールします:

```bash
taida install
```

- 依存ツリーを解決
- taida-community からパッケージをダウンロード
- `.taida/taida.lock` を生成

### `taida deps`

厳密な依存解決と検証を行います:

```bash
taida deps
```

- 全ての依存関係を解決
- 不足パッケージをインストール
- ロックファイルを更新
- ダイヤモンド依存の衝突を検出

### `taida update`

世代内の最新バージョンに依存パッケージを更新します:

```bash
taida update
```

- taida-community で新しいバージョンを確認
- lockfile を再生成

### `taida publish`

パッケージを taida-community に公開します:

```bash
taida publish [--label LABEL] [--dry-run]
```

- `taida auth login` 済みであること
- verify が破壊的変更を自動検知し、世代を決定
- git commit + tag + push 方式で公開
- 初回は `taida-community/proposals` に Issue を自動作成

---

## ロックファイル

ロックファイルは `.taida/taida.lock` に保存されます。全ての依存関係の正確な解決済みバージョンを記録します。

- バージョン管理にコミットする
- 再現可能なビルドを保証する
- `taida install`、`taida deps`、`taida update` で再生成される
- 世代指定（`@a`）を exact バージョン（`@a.47`）に解決・記録する

---

## 依存解決

### ダイヤモンド依存

2 つのパッケージが同じパッケージの異なるバージョンに依存している場合、両方がインストールされます。各パッケージは自分の packages.tdm に書いたものだけが見えます。

### プロバイダ

依存関係はプロバイダの連鎖を通じて解決されます:

| 優先度 | プロバイダ | ソース |
|--------|-----------|--------|
| 1 | ワークスペース | ローカルの `packages.tdm` |
| 2 | コアバンドル | Taida に同梱されたパッケージ |
| 3 | ストア | taida-community GitHub org |

---

## プロジェクト例

```taida
// packages.tdm
>>> utils/string-helpers@a.3
>>> data/json-tools@b.7

<<<@a.1 @(processData, DataResult)
```

```taida
// main.td
>>> utils/string-helpers@a.3 => @(capitalize, slugify)
>>> ./types.td => @(Article)

article <= Article(
  title <= capitalize("hello world"),
  slug <= slugify("hello world")
)

stdout(jsonEncode(article))
```

---

## 関連ドキュメント

- [モジュールガイド](/_corpus/guide/10_modules.md)
- [CLI リファレンス](/_corpus/reference/cli.md)
- [コミュニティガイド](/community.md)