cnb-rs ext create

cnb-rs ext create <NAME> [options]

创建新 extension 项目的 Rust 极简模板脚手架。

生成 6 个文件 + 1 个 src/ 子目录的完整项目骨架，开箱即可 cargo build 编译通过，可直接 cnb-rs ext install . 走 Local kind 安装本地测试（Phase 5 后续 task）或 push 到 CNB + 发 release 后通过 cnb-rs ext install 远程安装。

参数

• <NAME>：extension 名称
  • 必须以 cnb- 开头（与最终 binary 名一致）
  • 主体仅支持字母 / 数字 / 短横线（不允许 _ . 空格 / 特殊字符）
  • 主体不能以短横线开头或结尾

例：cnb-foo / cnb-my-tool-2 / cnb-stats3 ✓

反例：foo（缺前缀）/ cnb-（缺主体）/ cnb-foo_bar（下划线）/ cnb-foo.bar（点）/ cnb-foo-（末尾横线）

选项

• -p, --path <PATH>：目标路径（默认 $PWD/<NAME>）

故意不提供 --force 选项：目标路径已存在直接拒绝，避免误覆盖工作。要重新生成请先 rm -r <NAME> 再 create。

模板内容

模板对齐 cnb-stats / cnb-stars / cnb-chat 三个 official ext 的成熟做法：

文件	内容
Cargo.toml	极简 deps：anyhow + clap（不含 tokio / reqwest）；rust-version 1.86；release profile 含 strip + LTO
src/main.rs	minimal CLI 调 $CNB_BIN api /v2/user 示例；含 env var 完整注释
.cnb.yml	Phase 4 验证过的 CI/Release 配置：push 跑 fmt+clippy+test+build；tag_push 自动 build linux-amd64 + 创建 release + asset-upload
.gitignore	Rust 通用（/target/）+ 防误提交 cnb-<name>-*-* binary + OS dotfiles
README.md	install 三种方式 / 使用 / 环境变量 / build / release 完整说明
LICENSE	Apache-2.0 全文（与 cnb-rs 主仓一致）

模板内的 占位符在生成时会替换为不含 cnb- 前缀的命令名（例：cnb-foo → foo）。

设计决策（Phase 5）

• 仅 1 个 Rust 模板：不维护 Go 模板（需 SDK 维护爆炸） / 不维护 bash 模板（Windows 二等公民）
• 极简 deps：anyhow + clap 足够大多数 ext；需要 HTTP/async 时作者自行 cargo add tokio reqwest
• 默认 $PWD/cnb-<name>：可 -p/--path 覆盖
• 已存在拒绝：不提供 --force，让用户 rm 手动为上
• 创建后只提示不自动 install：避免「突然装了个东西」释问新手

完整设计见 .windsurf/docs/cnb-extension-design.md §12 Phase 5。

输出示例

成功生成

$ cnb-rs ext create cnb-demo
→ 在 /home/alice/projects/cnb-demo 创建 cnb-demo 项目...
✓ 项目骨架已生成（6 个文件）:
  - Cargo.toml
  - .cnb.yml
  - .gitignore
  - README.md
  - src/main.rs
  - LICENSE  (Apache-2.0)

下一步：
  cd /home/alice/projects/cnb-demo
  cargo build --release   # 验证模板能编译
  # 修改 src/main.rs 实现你的逻辑
  # cnb-rs ext install .   # Local kind 安装（Phase 5 后续 task）
  # 或 push 到 CNB → 发 release → cnb-rs ext install <user>/cnb-demo

自定义路径

$ cnb-rs ext create cnb-foo -p /tmp/playground/cnb-foo
→ 在 /tmp/playground/cnb-foo 创建 cnb-foo 项目...
✓ ...

NAME 校验失败

$ cnb-rs ext create foo
错误: extension 名称必须以 'cnb-' 开头，实际：'foo'

示例：cnb-rs ext create cnb-foo

$ cnb-rs ext create cnb-foo_bar
错误: extension 名称仅支持字母 / 数字 / 短横线，实际：'cnb-foo_bar'

提示：避免 _ . 空格 等字符（会导致 binary 命名 / git tag / CNB repo path 问题）

目标路径已存在

$ cnb-rs ext create cnb-demo
错误: 目标路径已存在：/home/alice/projects/cnb-demo

提示：先 rm 这个目录，或用 -p/--path 指定其他路径。
      本命令故意不提供 --force（避免误覆盖已有工作）

完整开发流程

# 1. 生成脚手架
cnb-rs ext create cnb-foo
cd cnb-foo

# 2. 验证模板能编译
cargo build --release
./target/release/cnb-foo --help

# 3. 修改 src/main.rs 实现你的逻辑（参考模板里的 $CNB_BIN api 调用示例）

# 4. 初始化 git 并 push 到 CNB
git init
git add .
git commit -m "✨ feat: cnb-foo 初始实现"
# 在 CNB Web UI 新建仓库 user/cnb-foo（或 cnb-rs create-repo CLI）
git remote add origin https://cnb.cool/user/cnb-foo.git
git push -u origin main

# 5. 打 tag 触发 release pipeline 自动 ship linux-amd64
git tag v0.1.0
git push origin v0.1.0
# 等 CI 完成 → 自动创建 release v0.1.0 + 上传 cnb-foo-linux-amd64

# 6. （可选）maintainer 本地 build + upload windows binary
cargo build --release
cp target/release/cnb-foo.exe cnb-foo-windows-amd64.exe
cnb-rs release asset-upload -t v0.1.0 -f cnb-foo-windows-amd64.exe

# 7. （可选）提 PR 到 wwvo/cnb-rs/cnb-extensions registry，让用户能短名安装：
#    在 extensions.toml 末尾追加 [[extension]] block

# 8. 用户安装
cnb-rs ext install user/cnb-foo        # 完整路径，立即可用
cnb-rs ext install cnb-foo             # 短名，需要先 PR 到 registry

退出码

• 0：项目生成成功
• 1：NAME 校验失败 / 目标路径已存在 / 写文件失败

另请参阅

• cnb-rs ext install — 安装生成的 extension
• cnb-rs ext search — 在 registry 中搜索 extension
• Extension 开发指南 — extension 工作原理 + 命名约定 + env var 注入
• Extension Registry — 把 PR 你的 ext 加入 registry