release-tool 0.2.1

# `release.toml` reference

## Top-level concepts

```toml
required_version = "0.1.0" # minimum release-tool SemVer，类似 cmake_minimum_required

[repository]
github = "owner/name"      # 必须与 origin identity 一致
branch = "main"            # release 只能从该 branch 的 remote HEAD 执行

[hooks]
preflight = ["just", "verify"] # 可空；argv，不经过 shell
```

```text
current release-tool crate < required_version
  -> 在完整 shape parsing 前拒绝，并要求更新 Cargo dependency/Cargo.lock

current release-tool crate >= required_version
  -> 按已定义字段语义读取；unknown field 仍拒绝，防止拼写错误
```

没有 `schema_version`、`version_file`、`RELEASE_TAG` 或 lifecycle command list。

## Command values

所有 project hooks 是 argv array：

```toml
build = ["just", "_build-release-image", "{image}"] # 一个 program + 两个 args

# 禁止：shell = "just build && just test"
```

```text
Supported placeholders
  {version} # resolved calendar tag
  {image}   # Docker target 的 resolved image（仅 build/local_check）
```

工具直接执行 argv，不调用 `sh -c`，因此空格、`$()`、`;` 不会被二次解释。

`preflight`、Docker `build` / `local_check` 的 native stdout/stderr 会实时继承到调用方。
接收 tool-injected credentials 的 `remote_check` 仍由工具 capture，并在错误输出前 redaction。

## GitHub Release publisher

```toml
[publishers.release]
kind = "github_release"
title = "CPE {version}"
prerelease = true
```

remote identity 是 GitHub Release tag + asset name。一个 Release 可以承载多个 target 的 assets。

## Docker archive target

```toml
[[targets]]
name = "sc"
kind = "docker_archive"
publisher = "release"
default = true
platform = "linux/amd64"
image = "cpe:{version}"
asset = "cpe-{version}-linux-amd64.tar.xz"
build = ["just", "_build-release-image", "sc", "{image}"]
local_check = ["just", "_check-release-image", "sc", "{image}"]
```

`asset` 必须是单一安全文件名。adapter 校验 image platform，执行 `docker save` + `xz`，并生成
GNU-compatible SHA-256 checksum file。

## GitHub Maven publisher

```toml
[publishers.packages]
kind = "github_maven"
settings = ".mvn/settings.xml" # repository-owned；只引用 env credentials
server_id = "github"
```

settings example：

```xml
<settings>
  <servers>
    <server>
      <id>github</id>
      <username>${env.GITHUB_ACTOR}</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
  </servers>
</settings>
```

token 由工具从 `gh` 读取，仅注入 Maven/remote-check child environment。

## Maven reactor target

```toml
[[targets]]
name = "maven"
kind = "maven_reactor"
publisher = "packages"
default = true
wrapper = "./mvnw"
pom = "pom.xml"
projects = ["jobs/cpe/cpe-job-model", "jobs/skycross/skycross-job-model"]
also_make = true
remote_check = ["just", "_check-published-maven", "{version}"]
```

```text
POM reactor model
  -> selected projects + internal dependencies when also_make=true
  -> derived groupId/artifactId/version/packaging
  -> planned jar/pom identities
```

配置不复制 `coordinates`。第一期为保持 adapter 小而可证明，接受以下 reactor subset：

```text
- selected modules 的 GAV 可从 module/parent direct fields 得到
- ${revision} 是 GAV 中唯一支持的 expression
- packaging: jar | pom
- main artifact + POM；不猜测 classifiers/attached artifacts
- duplicate GAV、unresolved expression 或其它 packaging 立即失败
```

这不是静默近似 Maven effective model：无法确定 exact deploy inventory 时停止，后续按真实 adopter
需求扩展解析能力。

完整 adopter 配置见 [`examples/`](../examples)。