cnb-rs ext preview

cnb-rs ext preview <REPO>[@<REF>] [--file <PATH>]

不下载 binary、不动 manifest、不写 lockfile —— 仅把指定 extension 仓库的 README.md（或 --file 指定的其它文件）打到 stdout，便于安装前 review。

与 cnb-rs skill preview 对称：装一个 extension 前先看一眼它的 README / manifest 决定要不要装。

参数

• <REPO>：仓库标识，支持三种形式
  • 完整路径 <owner>/<group>/<repo> 或 <owner>/<repo>
  • 完整 URL https://cnb.cool/<owner>/<repo>
  • 任意上述形式 + @<ref> 后缀（如 wwvo/cnb-rs/cnb-stats@v0.1.0）

选项

选项	默认	说明
--file <PATH>	README.md	要预览的文件路径，相对仓库根；常用替代：manifest.toml / CHANGELOG.md

行为：4 步流程

1. repo 解析：剥离可选 @ref 后缀，复用 crate::extension::install::parse_repo_input
2. ref 解析：复用 cnb_skills::ref_resolver::resolve（显式 @ref > 最新 release tag > 默认分支 HEAD）
3. 拉文件：单次 HTTP 走 client.get_raw_text(repo, "<ref>/<file>")
4. 输出：内容到 stdout，末尾自动补 \n（如果上游缺）

关键设计

stdout / stderr 严格分离

• stdout：100% 是文件原文，无任何前后缀
• stderr：进度行（📦 source / 🔖 ref / 📄 path / ─── README.md (N bytes) ───）

这让如下管道完全干净：

cnb-rs ext preview wwvo/cnb-rs/cnb-stats > /tmp/readme.md
cnb-rs ext preview wwvo/cnb-rs/cnb-stats | less
cnb-rs ext preview wwvo/cnb-rs/cnb-stats --file manifest.toml | tomlq .extension.version

不下载 binary

install 会拉 release zip + 校验 sha256 + 写 manifest；preview 不做：单次 HTTP 拉文本即返回，没有任何文件系统副作用，也不需要 --force / --pin 等 install 选项。

ref 解析与 install 一致

默认走 latest release tag → 默认分支 双 fallback：

• 显式 @v0.1.0：直接用 v0.1.0
• 不指定：先试 client.get_latest_release()，没 release 则 fallback 到 client.get_head() 拿默认分支

这意味着 preview 看到的就是 install 默认会装的版本的 README。

输出示例

预览 README.md（默认）

$ cnb-rs ext preview wwvo/cnb-rs/cnb-stats
📦 source: wwvo/cnb-rs/cnb-stats (host=cnb.cool, repo=wwvo/cnb-rs/cnb-stats)
🔖 ref:    v0.1.0
📄 path:   README.md
─── README.md (3812 bytes) ───

# cnb-stats

A cnb-rs extension for repository statistics ...

预览 manifest.toml + 指定 ref

$ cnb-rs ext preview wwvo/cnb-rs/cnb-stats@v0.0.9 --file manifest.toml
📦 source: wwvo/cnb-rs/cnb-stats@v0.0.9 (host=cnb.cool, repo=wwvo/cnb-rs/cnb-stats)
🔖 ref:    v0.0.9
📄 path:   manifest.toml
─── manifest.toml (412 bytes) ───

[extension]
name = "cnb-stats"
version = "0.0.9"
kind = "binary"
...

错误：仓库不存在 / 文件不存在

$ cnb-rs ext preview wwvo/cnb-rs/cnb-no-such-ext
错误: 拉 'README.md' 失败：wwvo/cnb-rs/cnb-no-such-ext (ref=main)

提示：
  - 文件路径是否正确？默认拿 README.md，可用 --file 指定别的（如 manifest.toml）
  - ref 是否存在？默认走 latest release tag → 默认分支

与 cnb-rs skill preview 的对比

维度	ext preview	skill preview
默认拉的文件	README.md（仓库根）	skills/<NAME>/SKILL.md
必填参数	<REPO>	<REPO> + <SKILL>
可选 --file	✅ 自定义路径	❌ 写死 SKILL.md
ref 解析	复用 cnb_skills::ref_resolver	复用 cnb_skills::ref_resolver
frontmatter 处理	不动	不注入 cnb-*（与 install 区别）

与 cnb-rs api 的差异

理论上 cnb-rs api /<repo>/-/file/raw/README.md 能拉同样内容，但 preview 额外做：

• 自动 ref 解析（latest release → 默认分支双 fallback；不必手动查 ref）
• 友好错误提示（指明可能的文件路径 / ref 问题）
• 与 install 完全一致的 repo 解析逻辑（同种短 URL / 路径形式都支持）

api 适合脚本组合自由度高的场景；preview 适合手敲一次看一眼的人类用户。

另请参阅

• cnb-rs ext install — 看完决定要装时用
• cnb-rs skill preview — 同款语义，针对 SKILL.md
• cnb-rs api — 更底层、更灵活的逃生通道