JSON 输出

数据命令使用 --json 后，会向 stdout 输出一个以换行结束的 JSON 文档，诊断写入 stderr。 log export 例外：它输出 JSON Lines，不接受 --json。

sow status -r demo --json | jq '.result.status'

顶层封装

每个 JSON 响应都有七个字段：

配置检查成功的示例：

{
  "schema": "sow.cli/v1",
  "command": "config check",
  "ok": true,
  "repository": null,
  "operation": null,
  "result": {"workspace": "/srv/repo", "repositories": 1, "dists": 2},
  "errors": []
}

实际输出只有一行，路径和计数随工作区变化。没有产生有意义结果就失败时，通常为 result: null。失败的 check 和部分成功的 add 仍可返回有用结果； ok 为 false 时也应保留它们。

数据库提交后的维护错误也可能返回已提交结果。 重试前查看结果、status 和操作日志。非零退出码不代表事务已经回滚。

错误

{"code":3,"class":"partial","message":"managed: batch partially succeeded"}

按 code 或 class 判断，不解析消息文本。分类有 runtime、usage、discovery、 config、partial、lock、integrity、rejected、interrupted。 分类对应关系和下一步见退出码。

身份标识

操作 ID 与构建快照 ID 保持字符串类型。操作 ID 可能超出 JavaScript 精确整数范围。 构建快照 ID 是补零至 20 位的十进制字符串：

{"operation":"8632724976452398569","built_generation":"00000000000000000004"}

此规则适用于 generation、built_generation、base_generation 和表示构建快照的 base。 期望状态修订号和计数仍是 JSON 数字。

SOW 按下列规则设置顶层 operation：

operation 为 null 不表示只读命令。create、prune、init、config check、repo ls 和 where 的顶层 repository 为 null；where 将具体仓库名称放在位置记录中。

Plain create 与 prune

sow create 在 result 中返回下列字段：

sow prune 在 result 中返回下列字段：

初始化与配置

解析后的签名设置可包含公钥指纹和证书快照摘要。指纹和摘要数组各自排序，不能按下标配对。 详见配置参考。

仓库与 Dist

repo ls 返回 result.repositories[]；repo new 与 repo show 直接返回一个仓库对象。 常见字段为 name、path、protected、dists、generation、desired_revision、 status、packages、memberships、config。 有相应信息时还会出现 dirty_reasons、recent_operation。操作摘要包含 id、kind、state、created_at、updated_at 和可选 error_class。 status.pending_operation、status.recent_operation 也使用这一结构。

packages 统计已存储包对象，memberships 统计期望 Dist 成员关系。 一个对象属于两个 Dist 时，分别计为一个包、两份成员关系。

dist ls 返回 result.dists[]；dist new 与 dist show 直接返回一个 Dist 对象： name、format、architectures、desired_members、built_members、generation、 dirty、status、effective_config_sha256、config，以及可选 dirty_reasons。

每个架构条目有 family 和 ecosystem_arch。例如 DEB 的规范族为 x86_64， 生态名称为 amd64。

repo rm 和 dist rm 返回 name、removed、noop。 repo migrate 返回 repository、repository_id、from_layout、to_layout、 schema_from、schema_to、phase、generation、grace_not_before、legacy_aliases、 complete，以及可选的 warnings。没有宽限期截止时间时，grace_not_before 为 null。 迁移中止告警会指出保留的暂存目录或未完成的清理。 仓库选择成功后，即使迁移失败，响应中也会保留所选仓库。 各阶段含义见 repo migrate。

add、rm 与 build

三者都报告操作后的仓库状态：repository、desired_revision、built_generation、dirty。

add 还返回 operation、accepted、failed、memberships_added、memberships_removed 和 items[]。每项包含 input、status；有相应信息时，还包含 format、coordinate、 sha256、各 Dist 的 dists 结果映射及 error。

每个 Dist 的结果为 accepted、excluded 或 limited。一个包在不同 Dist 中可以有不同 结果。limit 移除旧版本时，成员移除计数会增加。

rm 返回可选的 operation、removed[]、所选 dists、changes[] 和 check。 每条 removed 记录包含 dist、sha256、coordinate、name。 预览时 check: true；只有 prediction_complete: true 才表示预期文件列表完整。 rm 不删除包池字节。

build 返回 operation、考虑的 dists 和 noop。无需变更时不创建新构建快照。

status 与 check

status 返回 status、ready_to_copy、desired_revision、built_generation、 dirty_dists、dirty_reasons、pending、repository_locked。 可选字段有 pending_operation、recent_operation、lock_holder。

status 为 clean、dirty、recovering 或 error。pending 包含 count、bytes。 成功的状态查询可以返回任何仓库状态。ok: true 表示查询成功。发布或复制前，用 check 做完整校验。

check 返回 repository、status、ready_to_copy、built_generation、 desired_revision 和 layers[]。每层有 name、ok、checked、issues。

正常检查层依次为 config、state、public-modes、retained、package-bytes、 desired-membership、index、signature、generation-manifest。 存在活动布局转换时，改为前三层加 layout-transition。 脏仓库可以通过各项一致性检查，但仍因尚不可交付而返回 5。

changes

结果包含 repository、base、generation、dirty、changes[]，每项变更包含：

不传基线时与上一构建快照比较；基线 0 列出当前完整目录；数字基线与指定的已记录构建快照比较。 这是本地文件差异，远端变更使用 publish 和目标 gc。

包查询

包对象包含 sha256、format、coordinate、architecture、canonical_arch、pool_path、 filename、size、name、source、version、kind、storage、created_revision、dists、 built_dists。可选字段包括 epoch、release、RPM 的 payload_sha256、signature_key，以及 warning。

architecture 是原生名称（如 noarch、amd64），canonical_arch 为 x86_64、aarch64 或 neutral。storage 为 pool 或 pending，不表示远端发布状态。 dists 是期望成员，built_dists 是上次构建成员。 包对象的 coordinate 不含格式前缀，加上 format + ":" 后才是 CLI 坐标引用。 where 位置记录的坐标已含此前缀。每个位置包含 repository、dists、 built_dists、sha256 和 coordinate。

发布与维护

publish --rebind 使用普通 publish 结果结构。R2 目标 GC 只报告候选，不删除远端对象。

操作日志

log 返回 repository 和按新到旧排序的 operations[]。 log ID 返回 repository 与 detail，后者包含 operation、duration_ms、events、 packages、memberships 和 files。

payload_json、result_json 和事件的 detail_json 是包含 JSON 的字符串， 新的元数据构建操作在 payload_json 中包含 publication_time；旧日志与布局迁移可能没有该字段。 需要时单独解析这些 JSON 字符串：

sow log -r demo --json \
  | jq '.result.operations[] | .payload_json | fromjson'

log prune 返回 operation、repository、before、pruned、compaction_deferred。 仅日期参数按机器本地时区解析，before 包含解析后的时间戳。

log export 每行输出一个完整操作记录，没有顶层封装：

sow log export operations.jsonl -r demo
sow log export - -r demo

文件目标必须尚不存在，其直接父目录必须是真实目录，不能是符号链接。

在脚本中使用检查结果

#!/usr/bin/env bash
set -euo pipefail
sow check -r demo --json | jq -e '.ok' >/dev/null
sow changes 0 -r demo --json \
  | jq -r '.result.changes[] | [.phase, .op, .path] | @tsv'

此脚本检查本地仓库并输出当前文件清单。需要发布时，对已配置目标运行 sow publish TARGET。