release-tool 0.3.1

# release-tool

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

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

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

核心 invariant：

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

Release identity = (repository, tag, commit)

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

已支持 adapters：

```text
Target adapters
├── DockerArchiveTarget   # image -> tar.xz + SHA-256
├── MavenReactorTarget    # reactor model -> jar/pom inventory
└── OciImageTarget        # one image -> Build/Reuse/Existing manifest

Publisher adapters
├── GitHubReleasePublisher
├── GitHubMavenPublisher
└── OciRegistryPublisher  # push/remote-retag one OCI target
```

## Lifecycle

```text
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
```

普通 targets 可用 `depends_on` 形成 DAG。选择 target 会自动包含其 transitive dependencies；
Prepare、Publish、Verify 都按稳定拓扑顺序执行。v1 的 dependency handoff 限于
`oci_image -> oci_image`。

每个 phase 的 input/output/side-effect/failure contract 见
[`docs/lifecycle.md`](docs/lifecycle.md)。

## State 与 recovery

```text
COMPLETE -> Verify -> idempotent skip

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

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

OCI current tag / recovery
  -> Prepare 运行 project-owned reuse_check
  -> Existing 只验证，Reuse remote-retag，Build push
  -> current tag 永不覆盖

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

tag push 与 publication 的完整恢复矩阵见 [`docs/recovery.md`](docs/recovery.md)。

## CLI interface

```bash
# 环境、认证、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

# 全部 Verify 成功后，原子写出供 downstream consumer 使用的机器可读结果
cargo run --release --locked -p release-tool-runner -- \
  publish --release --result-file /tmp/release-result.json
```

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

`--result-file` 不改变 lifecycle，也不是 recovery state。它只在所有 selected targets 完成
Verify 与 remote check 后写入；target 顺序保持 resolved dependency order，OCI artifact 使用
digest-pinned reference。建议把 result 写到 worktree 外的临时路径，再由 project-owned consumer
读取。失败时不会用半写结果替换已有文件。

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

```just
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：

```toml
required_version = "0.1.0"
```

repository、publisher、target 与 argv hook reference 见
[`docs/configuration.md`](docs/configuration.md)，adopter 的完整配置见 [`examples/`](examples)。

Cargo registry consumption、runner 和版本锁定见
[`docs/consumption.md`](docs/consumption.md)。

完整设计与操作说明：

```text
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 与升级
```

开发门禁：

```bash
just check
```