wasmeld/docs/design/wit-package-management.md

WIT Package 管理

状态： Implemented

Manifest 版本： 1

Lock 版本： 1

边界

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

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。相同包名和版本不可覆盖。

组件目录

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

wasmeld.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 必须提交：

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 前比较完整传递依赖图、 来源和摘要，不一致时构建失败。

命令

# 将 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 自动执行相同的同步步骤：

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。
• 暂不包含认证、权限、废弃标记和垃圾回收。