release-tool

release-tool 是 computed-parameter repositories 共用的 release lifecycle engine。 项目声明 repository facts、Target 与 Publisher；工具统一处理 version、Git tag、 幂等检查、发布和失败恢复。

它不是 shell workflow DSL，也不承载项目自己的业务校验。

ReleaseIntent
    │
    ▼
ReleaseCandidate ── Target.resolve ──> ReleasePlan
    │                                      │
    │ Doctor / Inspect                     │ artifact identities 已冻结
    ▼                                      ▼
PreparedRelease  <── Target.prepare ── ArtifactManifest[]
    │
    ▼
SealedRelease    # remote annotated tag -> exact commit
    │
    ▼
Publication      # Publisher 只消费 manifest
    │
    ▼
VerifiedRelease

核心 invariant：

Release.version == Release.tag
Release.commit  == peeled remote annotated tag commit

Release identity = (repository, tag, commit)

# 已存在的 tag/artifact 永不移动、覆盖或删除。
# publication 只有 Verify 成功后才是 COMPLETE。

已支持 adapters：

Target adapters
├── DockerArchiveTarget   # image -> tar.xz + SHA-256
└── MavenReactorTarget    # reactor model -> jar/pom inventory

Publisher adapters
├── GitHubReleasePublisher
└── GitHubMavenPublisher

Lifecycle

Resolve  # read-only：冻结 release identity 与 artifact identities
Doctor   # 检查 commands、Git/gh、权限与 staging capability
Inspect  # read-only：ABSENT / COMPLETE / PARTIAL / INVALID
Prepare  # preflight + build + local verify；只写 staging/cache
Seal     # New only：为 exact commit 创建并 push annotated tag
Publish  # 只消费 ArtifactManifest；不 rebuild、不覆盖
Verify   # read-only：复核 tag、remote identity、bytes/provenance

每个 phase 的 input/output/side-effect/failure contract 见 docs/lifecycle.md。

State 与 recovery

COMPLETE -> Verify -> idempotent skip

GitHub Release PARTIAL
  -> 下载已有 assets 校验 digest
  -> 只补齐 missing assets

GitHub Maven PARTIAL
  -> stop；不覆盖既有 version

write response lost
  -> Inspect remote
  -> COMPLETE + exact verification 才按成功处理

tag push 与 publication 的完整恢复矩阵见 docs/recovery.md。

CLI interface

# 环境、认证、repository 与 destination capability
cargo run --release --locked -p release-tool-runner -- doctor

# read-only：显示 commit、tag、targets、artifact identities 与 tool version
cargo run --release --locked -p release-tool-runner -- plan
cargo run --release --locked -p release-tool-runner -- plan --release --all

# 当前 commit 已有 release tag：验证/补齐同一个 release
cargo run --release --locked -p release-tool-runner -- publish

# 当前 commit 无 tag：准备完成后创建下一条 calendar annotated tag
cargo run --release --locked -p release-tool-runner -- publish --release

publish 会实时报告 lifecycle phase；项目的 preflight/build/local-check 输出保持可见。 涉及 machine-readable output 或 tool-injected credentials 的命令仍由工具捕获和脱敏。

项目只保留 thin Cargo runner 和一条发布入口：

publish *args:
    cargo run --release --locked \
        -p release-tool-runner -- publish {{ args }}

Cargo 从 registry 自动获取 Cargo.lock 指定的 released crate、校验 checksum、编译并缓存。 不需要手工安装 binary，也不在运行时选择 mutable latest。

required_version 是 minimum version，不是 binary pin：

required_version = "0.1.0"

repository、publisher、target 与 argv hook reference 见 docs/configuration.md，三个 adopter 的完整配置见 examples/。

Cargo registry consumption、runner 和版本锁定见 docs/consumption.md。

完整设计与操作说明：

docs/domain-model.md    # Release / Target / Publisher / ArtifactManifest
docs/lifecycle.md       # 七个 phase 的完整 contract
docs/configuration.md   # 配置字段与 adapter 边界
docs/recovery.md        # 状态矩阵、重试与人工恢复
docs/migration.md       # 三个 adopter 的迁移顺序
docs/consumption.md     # Cargo registry dependency、thin runner 与升级

开发门禁：

just check