cnb-rs ext install

cnb-rs ext install <REPO> [options]

从 CNB release 安装 extension：下载平台匹配的 binary，SHA256 校验，落地到 $EXTENSIONS_DIR/cnb-<name>/，并写 manifest.toml 记录元数据供 list / upgrade 使用。

参数

<REPO>：仓库标识。支持三种形式：
- 完整路径：<owner>/<repo> 或 <owner>/<group>/<repo>，如 wwvo/cnb-rs/cnb-stats
- 完整 URL：https://<host>/<owner>/<group>/<repo>（含 .git 后缀自动去掉，trailing slash 自动 trim）
- 短名（Phase 5+）：如 cnb-stats，自动从 registry 查表展开为完整路径；找不到时报错并提示 cnb-rs ext search
- 本地路径（Phase 5+，Local kind）：如 . / ./cnb-foo / /abs/path/cnb-foo / C:\\path\\cnb-foo。指向一个 cargo project 目录（含 Cargo.toml 且 [package].name 以 cnb- 开头）。manifest 记 [local] path 字段，dispatch 时从 <path>/target/{release,debug}/ 实时找 binary（cargo build 后立即生效，不需重装）

选项

--pin <TAG>：安装指定 tag（默认装 latest release）。pinned extension 在 cnb-rs ext upgrade --all 时会跳过，需要 --force 才能升级
--force：已装时强制覆盖（删除现有目录重装）。默认情况下，已装 extension 会拒绝重复 install
--script：走 Script kind 安装（git clone 仓库 + shebang 脚本执行）。Windows 需 sh.exe (Git for Windows)，install 时 fail-fast 检测

继承的全局选项：

--domain <DOMAIN>：指定目标域名（默认：cnb.cool），当 <REPO> 是非 URL 形式时用作默认 host

行为：12 步安装流程

解析 repo：拆 URL host + path，校验 extension 名（最后一段必须以 cnb- 开头）
命名冲突检测：与 cnb-rs 内置子命令同名 → 拒绝（提示用 ext exec 显式调用）
已装检查：目录已存在且无 --force → 拒绝（提示用 upgrade 或 --force）
拉 release：调 GET /{repo}/-/releases/latest 或 GET /{repo}/-/releases/tags/{pin}
平台匹配：在 release assets 中找 cnb-<name>-<os>-<arch>[.exe]
下载 binary：用 plain HTTP client（无 auth header）GET asset 的 brower_download_url
SHA256 校验：asset 提供 hash_algo = "sha256" 时强校验（mismatch 中止，提示「可能中间人攻击」）
建目录：force 时先 remove_dir_all 旧目录
原子落地：先写 .tmp 临时文件再 rename 到 final binary 路径，防止下载中断导致 binary 残缺
chmod +x：Unix 平台设 0o755（Windows 跳过）
写 manifest.toml：原子写（先 .tmp 再 rename），记录 host / owner / repo / tag / kind / checksum
sanity check：跑一次 cnb-<name> --help，非 0 / 非 2 退出码报 warn 不阻断

平台 detection

asset 文件名约定：cnb-<name>-<os>-<arch>[.exe]

Rust target	cnb 约定 os	cnb 约定 arch
`x86_64-unknown-linux-gnu`	`linux`	`amd64`
`aarch64-unknown-linux-gnu`	`linux`	`arm64`
`x86_64-apple-darwin`	`darwin`	`amd64`
`aarch64-apple-darwin`	`darwin`	`arm64`（找不到时 fallback 到 `amd64`）
`x86_64-pc-windows-msvc`	`windows`	`amd64`（asset 名含 `.exe` 后缀）
`aarch64-pc-windows-msvc`	`windows`	`arm64`（asset 名含 `.exe` 后缀）

macOS arm64 fallback

M1 / M2 用户运行时，若 release 中没有 darwin-arm64 asset 但有 darwin-amd64，会自动 fallback 安装 amd64 版本并 stderr 提示需要 Rosetta 2（macOS 11+ 默认已装）。

输出示例

安装成功

$ cnb-rs ext install wwvo/cnb-rs/cnb-stats
⏬ 下载 cnb-stats-linux-amd64 (4521320 bytes) ...
✓ SHA256 校验通过
✓ extension 'cnb-stats' 安装成功
  版本：v0.1.0
  位置：/home/alice/.local/share/cnb/extensions/cnb-stats/cnb-stats

平台 fallback

$ cnb-rs ext install wwvo/cnb-rs/cnb-stats
⏬ 下载 cnb-stats-darwin-amd64 (5012456 bytes) ...
⚠ 当前平台 (darwin-arm64) 无原生 binary，使用 darwin-amd64 fallback
  需要 macOS Rosetta 2 才能运行（macOS 11+ 默认已装）
✓ SHA256 校验通过
✓ extension 'cnb-stats' 安装成功

pinned 安装

$ cnb-rs ext install wwvo/cnb-rs/cnb-stats --pin v0.0.9
⏬ 下载 cnb-stats-linux-amd64 (4321100 bytes) ...
✓ SHA256 校验通过
✓ extension 'cnb-stats' 安装成功
  版本：v0.0.9
  位置：/home/alice/.local/share/cnb/extensions/cnb-stats/cnb-stats
  pinned：是（upgrade --all 会跳过；--force 可强制升级）

错误示例（友好提示）

命名冲突

$ cnb-rs ext install wwvo/cnb-rs/cnb-auth
错误: extension 命令名 'auth' 与 cnb-rs 内置子命令冲突。

提示：维护者需要重命名仓库（如 'cnb-auth-x'），
      或用 'cnb-rs ext exec auth' 显式调用（绕过命名优先级）

已安装

$ cnb-rs ext install wwvo/cnb-rs/cnb-stats
错误: extension 'cnb-stats' 已安装。

提示：用 'cnb-rs ext upgrade stats' 升级，
      或加 --force 覆盖（会删除现有目录）

平台不匹配

$ cnb-rs ext install wwvo/cnb-rs/cnb-stats
错误: release v0.1.0 没有匹配当前平台 (linux-arm64) 的 asset。

预期 asset 名：'cnb-stats-linux-arm64'
实际 asset 列表：cnb-stats-linux-amd64, cnb-stats-darwin-amd64, cnb-stats-windows-amd64.exe

提示：请向维护者提 issue / PR 增加该平台 binary

SHA256 mismatch

$ cnb-rs ext install wwvo/cnb-rs/cnb-stats
⏬ 下载 cnb-stats-linux-amd64 (4521320 bytes) ...
错误: SHA256 校验失败：
  expected: abc123...
  actual:   def456...

提示：可能是中间人攻击 / asset 被替换，已中止安装

短名（从 registry 解析，Phase 5+）

$ cnb-rs ext install cnb-stats
⏬ 下载 cnb-stats-linux-amd64 (752700 bytes) ...
✓ SHA256 校验通过
✓ extension 'cnb-stats' 安装成功
  版本：v0.1.3
  位置：/home/alice/.local/share/cnb/extensions/cnb-stats/cnb-stats

cnb-rs 自动从 wwvo/cnb-rs/cnb-extensions registry 查到 cnb-stats 的完整 repo 路径（wwvo/cnb-rs/cnb-stats）后走 install flow。完整路径 / URL 形式不触发 registry fetch（fast path）。

Script kind 安装（git clone 仓库，shebang 脚本，Phase 5+）

$ cnb-rs ext install --script alice/cnb-whoami
📦 git clone https://cnb.cool/alice/cnb-whoami.git
✓ Script extension 'cnb-whoami' 安装成功
  Clone from: https://cnb.cool/alice/cnb-whoami.git
  Tag: git-abc1234
  Script: /home/alice/.local/share/cnb/extensions/cnb-whoami/cnb-whoami

Script kind 用 git clone 拉 default branch（--depth=1），仓库根必须有同名 shebang 脚本（如 cnb-whoami，无 .exe 后缀），文件首行 #!/bin/sh 或 #!/usr/bin/env bash。

Script kind 不支持 --pin（git clone 拉 default branch；要 pin 版本请 fork 仓库后切 branch）。

Script kind 不写 SHA256（git protocol 已 verify content）；manifest tag 用 git rev-parse --short HEAD 的结果（如 git-abc1234），fallback main。

Windows 时 fail-fast 检测 sh.exe

$ cnb-rs ext install --script alice/cnb-whoami
错误: Script kind extension 在 Windows 需要 sh.exe（Git for Windows 提供）。

请装 Git for Windows: https://git-scm.com/download/win
或选择 Binary kind extension（不要 --script flag）

检测方式：where sh.exe 在 install 入口立即跑，找不到立即拒绝。避免装上后调用时才报错的体验断裂。

dispatch Windows 自动 wrap sh.exe

# Windows 上调用 Script kind extension
$ cnb-rs whoami
# 内部等价于：sh.exe C:\Users\...\extensions\cnb-whoami\cnb-whoami
# （shebang 在 Windows 不 work，由 Git for Windows 的 sh.exe 解析 #!/bin/sh）

Unix（Linux/macOS）直接走 shebang，OS 内核自动调 interpreter。Windows 由 dispatch 自动 wrap sh.exe <script>，用户透明无感。

本地路径（Local kind，Phase 5+）

$ cnb-rs ext create cnb-myproj
→ 在 /home/alice/projects/cnb-myproj 创建 cnb-myproj 项目...
✓ 项目骨架已生成（6 个文件）...

$ cd cnb-myproj
$ cargo build --release   # 或 cargo build 走 debug fallback
$ cnb-rs ext install .
✓ Local extension 'cnb-myproj' 安装成功
  开发目录: /home/alice/projects/cnb-myproj
  命令调用: cnb-rs myproj

提示：修改 src/ 后运行 'cargo build --release'（或 'cargo build' 走 debug fallback），
      cnb-rs 调用时自动 pick 最新 binary 不需重装。

$ cnb-rs myproj --help     # dispatch 走 manifest [local] path → target/{release,debug}/cnb-myproj
cnb-myproj extension — TODO: 替换为你的一句话描述
...

Local kind 在 manifest 中记 [local] path = "..." 字段（绝对路径），dispatch 时 spawn <path>/target/release/cnb-myproj[.exe]，release 优先，fallback target/debug/。两者都没时给清晰错误提示。

Local kind 不支持 --pin（没有 release tag 概念）。需要发布版本请走 cargo build + git tag + 远端 cnb-rs ext install <user>/cnb-myproj。

Local kind binary 没 build

$ cnb-rs myproj
错误: extension 'cnb-myproj' 未安装；请用 'cnb-rs ext install cnb-myproj' 安装

这种情况是 <path>/target/{release,debug}/cnb-myproj 都不存在。在开发目录运行 cargo build --release（或 cargo build）即可。

短名找不到时

$ cnb-rs ext install cnb-nonexistent
错误: 短名 'cnb-nonexistent' 在 registry 中找不到。

提示：1) 'cnb-rs ext search cnb-nonexistent' 查看候选
      2) 'cnb-rs ext search --refresh' 强制刷新 cache
      3) 用完整路径如 'cnb-rs ext install user/group/cnb-nonexistent'

min_cnb_rs_version 检测（Phase 6+）

registry entry 可声明 min_cnb_rs_version 字段（SemVer 字符串），install 时若当前 cnb-rs 版本低于此值则拒绝并提示升级。

$ cnb-rs --version
cnb-rs 0.11.5 (...)

$ cnb-rs ext install cnb-newish
错误: extension 'cnb-newish' 要求 cnb-rs >= 0.13.0，当前版本 0.11.5。

提示：升级 cnb-rs 后重试：
  cnb-rs upgrade            # 自升级到最新 release
  # 或访问 https://cnb.cool/wwvo/cnb-rs/cnb-rs/-/releases 下载最新 binary

保守策略：以下情况一律放行（不阻塞 install）：
registry fetch 失败（offline / network issue）
registry 中没找到此 entry（用户装的可能是第三方 fork）
找到 entry 但 repo 字段与用户输入的 repo 不匹配（用户装的是 fork，不强制 registry 约束）
entry 没声明 min_cnb_rs_version（向后兼容老 registry）
min_cnb_rs_version 写了非法 SemVer（运行时保守放行 + warn；cnb-rs ext registry validate 在 PR/CI 阶段会拦截）

registry entry 的 min_cnb_rs_version 字段约束见 ext registry validate 文档。

退出码

0：安装成功
1：任何一步失败（解析 / 命名冲突 / 已装 / API / 下载 / 校验 / 写入）

与 `gh extension install` 的差异

特性	cnb-rs ext install	gh extension install
短名安装	✅ 从 `cnb-extensions` registry 解析（24h cache + 离线 fallback）	✅ 走 GH registry
完整路径	✅ owner/repo	✅ owner/repo
完整 URL	✅	✅
SHA256 校验	✅ 默认强校验（CNB Release API 提供 hash）	❌ 不校验
平台 fallback	✅ macOS arm64 → amd64	✅ 同
写 manifest 文件	✅ TOML，含 tag / pinned / kind	✅ YAML，类似字段
atomic move	✅ `.tmp` + rename	✅
命名冲突拦截	✅ install 时拦截	⚠ 部分拦截（dispatch 时再检测）
Local extension	✅ `cnb-rs ext install .` (manifest [local] path)	✅ `gh ext install .`
Script extension	✅ `--script` (git clone + sh.exe wrap on Windows)	✅ shebang + git clone

另请参阅

cnb-rs ext
cnb-rs ext list — install 后用 list 看 manifest 元数据
cnb-rs ext remove — 删除 extension
指南：cnb-rs extensions — 完整工作原理 + 安装目录约定

cnb-rs ext install ​

参数 ​

选项 ​

行为：12 步安装流程 ​

平台 detection ​

macOS arm64 fallback ​

输出示例 ​

安装成功 ​

平台 fallback ​

pinned 安装 ​

错误示例（友好提示） ​

命名冲突 ​

已安装 ​

平台不匹配 ​

SHA256 mismatch ​

短名（从 registry 解析，Phase 5+） ​

Script kind 安装（git clone 仓库，shebang 脚本，Phase 5+） ​

Windows 时 fail-fast 检测 sh.exe ​

dispatch Windows 自动 wrap sh.exe ​

本地路径（Local kind，Phase 5+） ​

Local kind binary 没 build ​

短名找不到时 ​

min_cnb_rs_version 检测（Phase 6+） ​

退出码 ​

与 gh extension install 的差异 ​

另请参阅 ​