JSON 输出

大多数 repository command 都有 JSON 形式，使用 --json：

graft status --json
graft diff --json --rows HEAD~1 HEAD data.sqlite

SQLite 扩展不提供 repository JSON PRAGMA。嵌入式应用应启动 CLI 并消费这些 稳定的 JSON 结果。

Repository Position

Field	含义
current_head	当前 commit id。
current_branch	当前 branch。
operation	mutation response 的操作名。

Path Entries

Field	含义
path	repository-relative path。
kind	sqlite_database、text_file 或 binary_file。
storage	sqlite_snapshot、inline 或 external。
change	added、modified 或 deleted。
index_status	staged 状态。
worktree_status	unstaged 状态。
code	Git-like 两字符状态码。
conflicted	是否有 unresolved conflict stages。

Status

graft status --json

常用字段：paths、counts、has_unstaged_changes、has_staged_changes、 has_conflicts、work_in_progress、staged_changes、unstaged_changes。

应用决定是否允许 switch、pull 或关闭 review flow 时，应优先使用 work_in_progress。

Diff 和 Conflicts

graft diff --json --rows HEAD~1 HEAD data.sqlite
graft conflicts --json

diff 的顶层 paths 适合做导航；SQLite database entries 在 --rows 时可以 包含 row-level payload。

每个 table entry 包含 columns、changes，声明主键的 table 还会包含 primary_key_columns。普通 rowid table 的 row change 使用 rowid； WITHOUT ROWID table 使用 key：

{
  "name": "docs",
  "primary_key_columns": ["space_id", "id"],
  "changes": [
    {
      "op": "update",
      "key": { "space_id": "space-1", "id": "doc-1" },
      "old_values": ["space-1", "doc-1", "before"],
      "values": ["space-1", "doc-1", "after"]
    }
  ]
}

主键 JSON 会保留 identity type。BLOB 主键字段使用 { "$blob": "00ff" } 这样的显式标记；同一个 key object 可以直接传给 graft resolve --row。

conflict JSON 可包含 rowid、声明主键或 semantic-key 类型的 row_conflicts， 以及 schema_conflicts、opaque_changes、blocked_reasons 和 apply_policy。

Files 和 Payloads

graft ls-files --json --details
graft payload status --json HEAD
graft payload fetch --json --remote origin HEAD
graft payload prune --json

使用这些输出构建文件浏览器、离线可用性面板和 payload cache 管理 UI。