register-catalog

用途

该技能帮助用户将他们的 Portolan 目录添加到 portolan-registry 中，方式是打开一个拉取请求。注册表会爬取并验证提交的目录，然后导出其元数据。Portolan 使用 STAC 来组织其 catalog.json，但 Portolan 目录是它自己的东西——不要称它为 STAC 目录。

主要能力

验证目录 URL 是否以 catalog.json 结尾、是否可访问，以及是否指向一个 Portolan 目录根。
从 URL 中推导出 slug（即包含 catalog.json 的目录名，也就是文件名之前的最后一个路径段）。
使用 gh 命令自动 fork、创建分支、添加文件并打开拉取请求。
提供替代方案：通过 portolan-sdi.org 的网页表单提交相同的 catalog.json URL。

使用方式

关键事实：提交者只提供 URL

注册表条目是一个仅含一个字段的 YAML 文件：

url: https://example.com/stac/catalog.json

CI 会自动爬取目录并提取其他所有内容（标题、描述、bbox、许可证、计数等）。永远不要添加其他字段或编造元数据——模式禁止这样做（additionalProperties: false）。

第 1 步：验证目录 URL

URL 必须以 catalog.json 结尾，并指向一个可访问的 Portolan 目录根。

curl -fsSL "$CATALOG_URL" | python3 -c "
import sys, json
c = json.load(sys.stdin)
assert c.get('type') == 'Catalog', f\"not a catalog root (type={c.get('type')})\"
print('OK:', c.get('id'), '-', c.get('title', '(no title)'))
"

如果 URL 不以 catalog.json 结尾、不可访问或不是目录根，请停止并告知用户。不要继续处理无效条目。

第 2 步：推导 slug

slug 是包含 catalog.json 的目录——文件名之前的最后一个路径段。无需自行编造。

# .../source-coop/nlebovits/ide-pergamino/catalog.json  ->  ide-pergamino
SLUG=$(basename "$(dirname "$CATALOG_URL")")
echo "$SLUG"

文件将是 catalogs/$SLUG.yaml。

第 3 步：打开 PR

使用 gh 来 fork（如果需要）、创建分支、添加文件并打开 PR——全部无需离开工作目录：

# CATALOG_URL 和 SLUG 从上述步骤延续

# Fork（如果已 fork 则无操作）并克隆到临时目录
TMP=$(mktemp -d)
gh repo fork portolan-sdi/portolan-registry \
  --clone "$TMP/portolan-registry" --remote
cd "$TMP/portolan-registry"

# 在新分支上创建条目
git checkout -b "add-$SLUG"
printf 'url: %s\n' "$CATALOG_URL" > "catalogs/$SLUG.yaml"
git add "catalogs/$SLUG.yaml"
git commit -m "Add $SLUG catalog"
git push -u origin "add-$SLUG"

# 向上游仓库打开 PR
gh pr create \
  --repo portolan-sdi/portolan-registry \
  --title "Add $SLUG catalog" \
  --body "Registers \`$CATALOG_URL\` in the Portolan registry."

第 4 步：报告

向用户提供 PR URL（由 gh pr create 打印），并解释 CI 将爬取并验证目录，然后在合并后将元数据导出到 exports/catalogs.json。

替代方案：网页提交

如果用户不想使用 GitHub，他们可以通过 portolan-sdi.org 的网页表单提交相同的 catalog.json URL。

适用场景

用户希望将 Portolan 目录注册到官方注册表。
用户偏好使用 GitHub 工作流（fork、分支、PR）进行提交。
用户需要自动验证目录 URL 并生成正确的注册表条目。

限制

提交的 URL 必须以 catalog.json 结尾，且指向可访问的 Portolan 目录根。
注册表条目 YAML 文件只能包含 url 字段，不能添加其他字段或编造元数据。
需要 GitHub 账户和 gh 命令行工具（或使用网页表单替代）。
元数据由 CI 自动提取，提交者无法手动指定。