# WIT Package 管理

**状态：** Implemented

**Manifest 版本：** 1

**Lock 版本：** 1

## 边界

`wasmeld-console` 作为版本化 WIT Registry 和管理面。组件构建侧由 `wasmeld`
解析依赖、锁定摘要并生成本地 `wit/deps`。`wit-bindgen` 始终只读取本地文件，
Component 运行时不访问 Registry。

```text
WIT Git tag
    |
    v
Wasmeld Registry
    |
    v
wasmeld -> wit.lock -> wit/deps -> wit-bindgen
```

WIT 源码不按版本复制目录。每个 package 只维护当前源码，发布时用
`service/v1.0.0`、`clock/v1.1.0` 等 Git tag 标记源码版本。Registry 保存由
Component Model 工具链编码的标准二进制 WIT Package，并从制品本身解析包名、
版本、直接依赖和 SHA-256。相同包名和版本不可覆盖。

## 组件目录

```text
components/clock-probe/
├── Cargo.toml
├── wasmeld.toml
├── wit.lock
├── src/lib.rs
└── wit/
    ├── world.wit
    └── deps/        # 自动生成，不提交
```

`wasmeld.toml` 当前只接受精确版本：

```toml
schema_version = 1

[registry]
url = "http://127.0.0.1:8080"

[dependencies]
"wasmeld:clock" = "0.1.0"
"wasmeld:service" = "0.1.0"

[replace."wasmeld:clock"]
path = "../../wit/clock"

[replace."wasmeld:service@0.1.0"]
path = "../../wit/service"
```

精确版本 replace 的优先级高于包级 replace。只有根组件的 replace 生效；依赖包
自身不能修改整个依赖图。替换目录声明的 WIT package 名称和版本必须与依赖完全
相同。没有 replace 的直接依赖和传递依赖从 `[registry].url` 获取。

## 锁文件

`wit.lock` 必须提交：

```toml
schema_version = 1

[[package]]
name = "wasmeld:clock"
version = "0.1.0"
source = "registry+http://127.0.0.1:8080"
sha256 = "..."
replaced = false
```

Registry 依赖的摘要覆盖完整二进制包；path replace 的摘要覆盖包目录下排序后的
顶层 `.wit` 文件名和内容。`--locked` 在安装 `wit/deps` 前比较完整传递依赖图、
来源和摘要，不一致时构建失败。

## 命令

```bash
# 将 WIT 源码编码成标准二进制 WIT Package
cargo run -p wasmeld-package --bin wasmeld -- \
  wit build wit/service

# 构建并发布；也可用 WASMELD_REGISTRY 设置 Registry
cargo run -p wasmeld-package --bin wasmeld -- \
  wit publish wit/service --registry http://127.0.0.1:8080

# 获取依赖并更新 wit.lock
cargo run -p wasmeld-package --bin wasmeld -- \
  wit fetch --manifest components/clock-probe/wasmeld.toml

# 验证锁文件，不更新
cargo run -p wasmeld-package --bin wasmeld -- \
  wit fetch --manifest components/clock-probe/wasmeld.toml --locked

# 查看实际来源
cargo run -p wasmeld-package --bin wasmeld -- \
  wit graph --manifest components/clock-probe/wasmeld.toml

# 添加或删除本地替换
cargo run -p wasmeld-package --bin wasmeld -- \
  wit replace wasmeld:clock@0.1.0 \
  --path ../../wit/clock \
  --manifest components/clock-probe/wasmeld.toml

cargo run -p wasmeld-package --bin wasmeld -- \
  wit replace wasmeld:clock@0.1.0 \
  --drop \
  --manifest components/clock-probe/wasmeld.toml
```

`pack` 自动执行相同的同步步骤：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  pack components/clock-probe/Cargo.toml --locked
```

## Registry API

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/api/v1/wit/packages` | 列出全部包版本 |
| `POST` | `/api/v1/wit/packages` | multipart 发布 `package.wasm` |
| `GET` | `/api/v1/wit/packages/{namespace}/{name}/{version}` | 查询元数据 |
| `GET` | `/api/v1/wit/packages/{namespace}/{name}/{version}/content` | 下载二进制包 |

Console 管理面提供同一 Registry 的列表、发布和下载操作。Registry 元数据不接受
客户端填写，服务端以二进制包解析结果为准。

## 当前边界

- 依赖版本必须是精确 SemVer，不解析版本范围。
- Registry 使用本地文件系统持久化，默认目录为 `var/wasmeld/wit-packages`。
- Registry 不保存 Git 仓库或源码；Git tag 与 commit 由源码仓库管理。
- 本地 `replace` 只支持目录，不支持 Git replace。
- 暂不包含认证、权限、废弃标记和垃圾回收。