cnb-rs ext registry

cnb-rs ext registry <subcommand>

管理 cnb-rs extension registry 的 maintainer 工具集。

当前用户最常用的 registry 操作是 cnb-rs ext search（查询 registry）。本组子命令面向 registry repo maintainer（即 wwvo/cnb-rs/cnb-extensions 维护者）以及 PR contributor。

可用子命令

子命令	说明
validate	校验本地 extensions.toml 是否符合 registry schema
refresh	从 CNB API 刷新 entry 的 stars / latest_release / latest_release_at 元数据（Phase 6+）

validate

cnb-rs ext registry validate <FILE>

校验本地 extensions.toml 文件的 schema 合法性，给 CI/PR 用。

校验规则

#	规则
1	每个 entry 的 name 必须以 cnb- 开头
2	每个 entry 的 repo 必须含 /（CNB 路径形式，如 user/cnb-foo 或 user/group/cnb-foo）
3	每个 entry 的 kind 必须为 binary 或 script（不允许 local，因 Local kind 仅本地开发用）
4	每个 entry 的 description 不能为空（trim 后）
5	entry name 在整个 registry 中不能重复
6	若 min_cnb_rs_version 字段存在，必须是合法的 SemVer 字符串（Phase 6+）

TOML 反序列化阶段已校验「字段全部必填」（缺 name / repo / description / official / kind 任一字段 → fail）；min_cnb_rs_version 为可选字段，缺失时跳过此校验。

参数

• <FILE>：待校验的 extensions.toml 文件路径（绝对或相对）

退出码

• 0：校验通过
• 1：文件不存在 / TOML 解析失败 / Schema 校验失败（任一规则违反）

输出示例

校验通过

$ cnb-rs ext registry validate extensions.toml
✓ extensions.toml 校验通过，3 个 entry

Schema 违规

$ cnb-rs ext registry validate bad.toml
错误: Schema 校验失败：bad.toml: entry #2 (cnb-foo): kind 'local' 必须为 'binary' 或 'script'

$ cnb-rs ext registry validate bad.toml
错误: Schema 校验失败：bad.toml: entry #1: name 'foo' 必须以 'cnb-' 开头

$ cnb-rs ext registry validate dup.toml
错误: Schema 校验失败：dup.toml: entry #2: name 'cnb-foo' 在 registry 中重复出现（每个 name 必须唯一）

$ cnb-rs ext registry validate bad-min.toml
错误: Schema 校验失败：bad-min.toml: entry #1 (cnb-foo): min_cnb_rs_version 'garbage' 不是合法 SemVer：unexpected character 'g' while parsing major version number

TOML 解析失败

$ cnb-rs ext registry validate broken.toml
错误: TOML 解析失败：broken.toml: ...

refresh

cnb-rs ext registry refresh <FILE> [--dry-run]

从 CNB API 刷新每个 entry 的元数据字段（Phase 6+，design §7.3）：

• stars — 仓库当前 star 数（调 GET /{repo} 取 star_count）
• latest_release — 最新 release tag（调 GET /{repo}/-/releases/latest 取 tag_name）
• latest_release_at — 最新 release 发布时间（同上取 published_at）

写回时保留头部注释块（首个 [[extension]] 之前的所有 # 注释 + 空行原样保留）。

参数

• <FILE>：待刷新的 extensions.toml 文件路径
• --dry-run：不写回文件，把新内容打到 stdout（CI/本地 diff 预览）

退出码

• 0：refresh 完成（即使部分 entry 的 API 调用失败也算成功，缺失字段保留旧值）
• 1：文件不存在 / TOML 解析失败 / 序列化失败 / 写入失败

输出示例

$ cnb-rs ext registry refresh extensions.toml
✓ refreshed wwvo/cnb-rs/cnb-chat
✓ refreshed wwvo/cnb-rs/cnb-stats
✓ refreshed wwvo/cnb-rs/cnb-stars

✓ refresh 完成 — 3 个 entry 已刷新（0 个 API 调用失败但已 fallback 保留旧值）
  文件已写回：extensions.toml

$ cnb-rs ext registry refresh extensions.toml --dry-run
# 头部注释保留...
[[extension]]
name = "cnb-chat"
...
stars = 42
latest_release = "v0.1.4"
latest_release_at = "2026-05-19T12:08:31Z"

--- DRY-RUN: 以下内容将写入 extensions.toml ---
...

错误降级

• get_by_id 调用失败：warning 后跳过 stars 更新（保留旧值，不报错退出）
• get_latest_release 调用失败：warning 后跳过 latest_release 更新（仓库可能还没 release）

保守策略保证 refresh 不会因为单个 entry 的 API 故障而中止整批刷新。所有 entry 都尝试刷新后才退出。

CI 集成（CNB crontab）

# cnb-extensions/.cnb.yml
main:
  'crontab: 0 0 * * *': # 每日 UTC 00:00
    - name: refresh-registry-metadata
      docker:
        image: rust:latest
      stages:
        - name: download cnb-rs
          script: |
            set -eu
            VERSION="nightly-20260519-xxx"  # Phase 6 Task B 或更新
            curl -fL -o /tmp/cnb-rs.tar.gz "https://cnb.cool/wwvo/cnb-rs/cnb-rs/-/releases/download/${VERSION}/cnb-rs-${VERSION}-x86_64-unknown-linux-musl.tar.gz"
            tar -xzf /tmp/cnb-rs.tar.gz -C /tmp
            install /tmp/cnb-rs-${VERSION}-x86_64-unknown-linux-musl/cnb-rs /usr/local/bin/cnb-rs
        - name: refresh + commit if changed
          script: |
            set -eu
            cnb-rs ext registry refresh extensions.toml
            git config user.email "bot@cnb-extensions"
            git config user.name "registry-refresh-bot"
            git add extensions.toml
            git diff --cached --quiet || git commit -m "🤖 chore(registry): daily metadata refresh"
            # git push 需要在 .cnb.yml 之外配置 git push token；详见 CNB 文档

配置后需运行 cnb-rs build crontab-sync main 一次让 CNB 平台识别新 cron。

Dogfood

wwvo/cnb-rs/cnb-extensions 仓库的 .cnb.yml 在 push CI 调本命令：

$:
  push:
    - docker:
        image: rust:latest
      stages:
        - name: validate extensions.toml schema
          script: |
            curl -fL -o /tmp/cnb-rs.tar.gz "https://cnb.cool/wwvo/cnb-rs/cnb-rs/-/releases/download/<VERSION>/cnb-rs-<VERSION>-x86_64-unknown-linux-musl.tar.gz"
            tar -xzf /tmp/cnb-rs.tar.gz -C /tmp
            install /tmp/cnb-rs-<VERSION>-x86_64-unknown-linux-musl/cnb-rs /usr/local/bin/cnb-rs
            cnb-rs ext registry validate extensions.toml

PR 提交时 schema 违规直接 fail，避免合并后破坏 cnb-rs ext search 用户。

完整示例

# 校验官方 registry repo
$ git clone https://cnb.cool/wwvo/cnb-rs/cnb-extensions.git
$ cd cnb-extensions
$ cnb-rs ext registry validate extensions.toml
✓ extensions.toml 校验通过，3 个 entry

# 准备 PR 加新 entry 前本地预校验
$ vim extensions.toml   # 加 [[extension]] block
$ cnb-rs ext registry validate extensions.toml
✓ extensions.toml 校验通过，4 个 entry

# CI 集成（PR 触发，schema 违规 fail）
$ cnb-rs ext registry validate extensions.toml || exit 1

另请参阅

• cnb-rs ext search — registry 客户端，用户查询用
• cnb-rs ext install — install 时短名解析也读 registry
• Extension Registry repo — 官方 registry 源
• registry schema 设计 — extensions.toml 字段语义