extension-template

cnb-rs extension 的官方项目模板。fork 此仓库，改个名字、写几行业务代码、push tag，就能 cnb-rs ext install 安装。

本仓库本身不是可安装的 extension —— 它没有 release，也不能被 cnb-rs ext install。它是脚手架，专门用来被 fork 或被 cnb-rs ext create（Phase 5）实例化。

把本仓库 fork 到你自己的 group / sub-group 下，改名为 cnb-<your-name>（必须以 cnb- 开头，这是 cnb-rs extension 的命名约定）：

# 例：fork 到 alice/projects/cnb-stats

把 cnb-myext（template 占位符）全局替换为你真实的命令名 cnb-<your-name>：

替换 src/main.rs 里的 demo 逻辑（调 GET /user 打印用户名）为你自己的业务。完整 CNB OpenAPI 文档见：

• CNB OpenAPI 索引
• cnb-api Rust crate（cnb-rs 自家维护的 Rust 客户端，推荐用于复杂 extension）

cargo build --release
./target/release/cnb-myext
# 应该报错：缺少 CNB_TOKEN 环境变量

模拟 cnb-rs dispatch 的 env var 注入：

CNB_TOKEN=your_token_here \
CNB_DOMAIN=cnb.cool \
CNB_REPO=alice/projects/cnb-stats \
./target/release/cnb-myext

输出应该看到 👋 Hello from cnb-myext + 你的用户名。

.cnb.yml 已经配好：push 任何 v* tag 时，CNB Pipeline 自动 build 3 个平台 binary（linux-amd64 / linux-arm64 / darwin-arm64）+ 创建 release + 上传 asset。

git tag v0.1.0
git push origin v0.1.0

等待 5-10 分钟 CI 跑完，去 CNB 上看 Release 页面应该有 3 个 binary + 1 个 sha256sums.txt。

cnb-rs ext install alice/projects/cnb-stats
# 输出：
# ⏬ 下载 cnb-stats-linux-amd64 (XXX bytes) ...
# ⚠ asset 未提供 SHA256（hash_algo="none"），跳过校验
# ✓ 安装成功：cnb-stats (v0.1.0)

然后即可用 cnb-rs stats 调用你的 extension。

cnb-rs ext install 对 release asset 命名有强约束，必须严格遵守：

CNB Pipeline 当前不提供 macOS / Windows runner，也不提供 cross-build 环境（macOS SDK 授权问题）。 为了让 template 「开箱即用」，.cnb.yml 默认只 build linux-amd64 / linux-arm64，这覆盖了 90%+ 的 cnb-rs 用户（服务器 / CI / WSL）。

三个选项：

1. 本地 build + 手工上传（推荐）：

   # 在你的 Mac 上（本地有 Xcode / clang）
   cargo build --release --target aarch64-apple-darwin
   cp target/aarch64-apple-darwin/release/cnb-myext ./cnb-myext-darwin-arm64
   # 然后去 CNB Release UI 手工 upload
   

2. 用 GitHub Actions 补充： fork 后加 .github/workflows/release-mac-win.yml，用 GitHub 免费的 macOS / Windows runner build， 然后用 cnb-cli 在 GitHub Action 里上传到 CNB release。

3. 在 cnb-rs ext install 依赖 Rosetta 2： cnb-rs install.rs 有 darwin-arm64 → darwin-amd64 的 fallback，但本项目默认两者都不 build，所以 fallback 也没用。 macOS 用户请用选项 1 或 2。

extension-template/
├── README.md              # 本文件
├── .cnb.yml               # CNB Pipeline：CI + release build + asset upload
├── .gitignore             # 标准 Rust gitignore + zigbuild 临时产物
├── LICENSE                # MIT
├── Cargo.toml             # 极简依赖：reqwest + serde + tokio + anyhow
├── src/
│   └── main.rs            # 示例代码：调 GET /user，演示 env var 注入
└── examples/
    └── bash-extension.sh  # bash 极简等价版（10 行搞定的 extension 用它更快）

cnb-rs extension 支持多种写法，本模板默认是 Rust binary。各方案对比：

Phase 5 计划：cnb-rs ext install 增加对 interpreted script 的原生支持（自动 detect kind = "script" + 跨平台 shell 启动）。当前 Phase 3 仅 binary kind，所以 bash 版本需要用户手工放进 extensions 目录，不能 cnb-rs ext install。

cnb-rs dispatch extension 时会注入下列 env var（详见 cnb-rs extensions guide）：

extension 直接 std::env::var() 读即可，无需自己解析 auth 文件 / 配置。

Cargo.toml 的默认依赖是极简的 reqwest + serde，目的是让 template 上手最快、依赖最少。如果你的 extension 要调多个 CNB API、或者需要类型化的请求 / 响应，推荐改用 cnb-rs 自家的 cnb-api crate：

[dependencies]
# 替换 reqwest + serde + serde_json 为：
cnb-api = { git = "https://cnb.cool/wwvo/cnb-rs/cnb-rs.git", tag = "v0.12.1", package = "cnb-api" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
anyhow = "1"

然后 src/main.rs 改为：

use cnb_api::CnbClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let token = std::env::var("CNB_TOKEN")?;
    let endpoint = std::env::var("CNB_API_ENDPOINT")
        .unwrap_or_else(|_| "https://api.cnb.cool".into());
    let client = CnbClient::new(endpoint, token);
    let user = client.users().get_current_user().await?;
    println!("当前用户: {}", user.username);
    Ok(())
}

cnb-api 提供完整的类型化客户端（auto-generated from OpenAPI spec），覆盖所有 CNB OpenAPI 端点。代价是依赖 cnb-rs main 仓库（git dep），编译时间略长（约 2 分钟首次 compile）。

每次 push 到 main 或开 PR 时自动跑：

1. cargo fmt --all -- --check（格式检查）
2. cargo clippy --all-targets --all-features -- -D warnings（lint 全 deny）
3. cargo test --all-features（单元测试）

push 任何 v0.1.0 / v1.2.3-rc1 等 v* tag 时自动跑：

1. 装 cargo-zigbuild + 3 个 cross-compile target
2. 串行 build 3 个平台 binary
3. 生成 sha256sums.txt（SHA256 hash 集合，cnb-rs ext install Phase 6 会用）
4. 创建 CNB Release（用 git:release action）
5. 上传 4 个 asset（3 binary + sha256sums.txt）到 release

Phase 4 MVP 已知限制：cnbcool/attachments 插件不会自动填 release asset 的 hash_algo / hash_value 字段，所以 cnb-rs ext install 当前会 warning「skip SHA256 校验」继续装。Phase 6 增强会读取 sha256sums.txt sidecar 文件做强校验，届时本模板的 .cnb.yml 无需修改（sidecar 已经在上传）。

cnb-myext 是占位符名字，给你 fork 后改成真实名字（如 cnb-stats）的「待替换样品」。我们故意不用 cnb-template 之类的名字，避免你忘记改名导致仓库里有「template-style」字样残留。

可以。bash 版见 examples/bash-extension.sh；其它语言（Python / Node / Go）只需遵守：

1. release asset 命名：cnb-<name>-<os>-<arch>[.exe]
2. 从 env var 读 CNB_TOKEN 等（cnb-rs dispatch 时注入）
3. 输出到 stdout / stderr（cnb-rs 直接透传）

把 .cnb.yml 的 build stage 改成你的语言的打包逻辑即可。

CNB Pipeline 不提供 macOS / Windows 构建环境，本 template .cnb.yml 默认只 build linux 平台。 三个解决方案详见上面「需要 macOS / Windows binary 怎么办」节。

最常用的临时方案：Windows 用户装 WSL，macOS 用户本地 cargo build 后手工上传到 release。

Phase 5 会增加 interpreted script kind 支持，到时 Python / Node / Bash 脚本 extension 可以 跨平台一份 asset 闯天下，不再需要多平台 binary。

当前（Phase 4 / cnb-rs 0.12.x）：

• 模板已经在上传 sha256sums.txt，asset 命名也对齐 cnb-rs ext install 期望
• 但 cnb-rs ext install 当前只校验 release API 返回的 asset.hash_algo == "sha256"，而 CNB API + cnbcool/attachments 链路暂不填这个字段，所以校验被跳过
• Phase 6 cnb-rs 增强：会读取 sha256sums.txt sidecar 做校验，届时无需用户改任何代码

模板的 .cnb.yml release 阶段只在 push tag 时触发。本地手工模拟：

# build 3 个平台
cargo zigbuild --release --target x86_64-unknown-linux-gnu
cargo zigbuild --release --target aarch64-unknown-linux-gnu
cargo zigbuild --release --target aarch64-apple-darwin

# 重命名到 cnb-rs 期望的 asset 名
mkdir -p dist/
cp target/x86_64-unknown-linux-gnu/release/cnb-myext dist/cnb-myext-linux-amd64
cp target/aarch64-unknown-linux-gnu/release/cnb-myext dist/cnb-myext-linux-arm64
cp target/aarch64-apple-darwin/release/cnb-myext dist/cnb-myext-darwin-arm64

# 生成 SHA256
cd dist && sha256sum cnb-myext-* > sha256sums.txt && cat sha256sums.txt

然后手工上传到 CNB Release UI 即可。

• cnb-rs ext install — 完整 install 流程 + 12 步说明
• cnb-rs ext upgrade — 升级机制（24h 后台 check + state.toml）
• cnb-rs extensions guide — 完整 extension 设计文档
• CNB OpenAPI — 完整 API 文档
• cnb-hello 演示 extension — 基于本模板实例化的最简 demo（用于 cnb-rs 自身 e2e 测试）

MIT