JSON 输出

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

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

嵌入式应用可以启动 CLI 并消费这些稳定的 JSON 结果，也可以使用 Node.js SDK 维持常驻的进程内 repository session。

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。

直接比较 SQLite 文件

graft diff --no-index --json --rows old.sqlite new.sqlite

这个 repository-independent response 不包含 repository paths，而是返回：

Field	含义
from、to	每个物理 side 的 path 和捕获到的 page_count。
changed	stable SQLite page content 是否不同。
kind	固定为 sqlite_database。
rows	是否请求 logical row expansion。
row_diff	logical status、capabilities、limitations、schema、tables、opaque changes 和 telemetry；仅在 changed pair 使用 --rows 时存在。

SQLite Page Delta

graft delta create --base old.sqlite --target new.sqlite --output update.graft-delta --json
graft delta inspect update.graft-delta --json
graft delta apply --base old.sqlite --delta update.graft-delta --output restored.sqlite --json

顶层 operation 是 sqlite_delta_create、sqlite_delta_inspect 或 sqlite_delta_apply。路径字段标识显式输入与 create-new 输出。嵌套的 delta、 metadata 或 result 包含 format、header_bytes、page_bytes、base/target 精确字节数与 SHA-256、changed_pages、delta_bytes 和 beneficial。

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。