Skip to content

cli-json.md

Latest commit

 

History

History
474 lines (368 loc) · 7.56 KB

cli-json.md

File metadata and controls

474 lines (368 loc) · 7.56 KB
Raw

CLI JSON Output

This document defines the JSON output schemas returned by grite when --json is provided. Schemas are versioned independently of the WAL schema.

Envelope

All JSON responses use a common envelope:

{
  "schema_version": 1,
  "ok": true,
  "data": { }
}

Errors are returned as:

{
  "schema_version": 1,
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "issue not found",
    "details": { }
  }
}

Error codes (stable)

  • invalid_args: CLI usage error or invalid flag value
  • not_found: issue/actor/ref not found
  • conflict: lock conflict or concurrent WAL update
  • db_busy: data dir owned by another process or daemon
  • io_error: filesystem error
  • git_error: git command or ref failure
  • wal_error: malformed WAL data or hash mismatch
  • ipc_error: daemon IPC failure
  • internal_error: unexpected error

Exit codes

  • 0: success (ok: true)
  • 2: invalid arguments
  • 3: not found
  • 4: conflict or lock violation
  • 5: environment error (not a git repo, missing config, db busy)
  • 1: any other failure

Common types

All IDs are lowercase hex without 0x:

  • actor_id: 16-byte hex
  • issue_id: 16-byte hex
  • event_id: 32-byte hex

Times are ts_unix_ms (milliseconds since Unix epoch).

For event objects:

  • actor is an actor_id
  • parent is an event_id or null

Issue summary

{
  "issue_id": "...",
  "title": "...",
  "state": "open",
  "labels": ["bug", "p0"],
  "assignees": ["alice"],
  "updated_ts": 1700000000000,
  "comment_count": 3
}

Event

{
  "event_id": "...",
  "issue_id": "...",
  "actor": "...",
  "ts_unix_ms": 1700000000000,
  "parent": null,
  "kind": { "IssueCreated": { "title": "...", "body": "...", "labels": ["bug"] } }
}

Ordering

  • Issue lists are sorted by issue_id (lexicographic).
  • Event lists are sorted by (issue_id, ts_unix_ms, actor, event_id).

Command outputs

The JSON blocks below describe the data payload inside the envelope.

grite init

{
  "actor_id": "...",
  "data_dir": ".git/grite/actors/<actor_id>",
  "repo_config": ".git/grite/config.toml"
}

grite actor init

{
  "actor_id": "...",
  "label": "work-laptop",
  "data_dir": ".git/grite/actors/<actor_id>"
}

grite actor list

{ "actors": [ { "actor_id": "...", "label": "...", "data_dir": "..." } ] }

grite actor show

{ "actor": { "actor_id": "...", "label": "...", "created_ts": 1700000000000 } }

grite actor current

{ "actor_id": "...", "data_dir": "...", "source": "repo_default|env|flag|auto" }

grite actor use

{ "default_actor": "...", "repo_config": ".git/grite/config.toml" }

grite issue create

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue update

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue comment

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue close

{ "issue_id": "...", "event_id": "...", "state": "closed", "wal_head": "<git-commit-hash>" }

grite issue reopen

{ "issue_id": "...", "event_id": "...", "state": "open", "wal_head": "<git-commit-hash>" }

grite issue label add|remove

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue assignee add|remove

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue link add

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue attachment add

{ "issue_id": "...", "event_id": "...", "wal_head": "<git-commit-hash>" }

grite issue dep add

{
  "event_id": "...",
  "issue_id": "...",
  "target": "...",
  "dep_type": "blocks",
  "action": "added"
}

grite issue dep remove

{
  "event_id": "...",
  "issue_id": "...",
  "target": "...",
  "dep_type": "blocks",
  "action": "removed"
}

grite issue dep list

{
  "issue_id": "...",
  "direction": "dependencies|dependents",
  "deps": [
    { "issue_id": "...", "dep_type": "blocks", "title": "..." }
  ]
}

grite issue dep topo

{
  "issues": [
    { "issue_id": "...", "title": "...", "state": "open", "labels": ["..."] }
  ],
  "order": "topological"
}

grite issue list

{ "issues": [ { "...": "IssueSummary" } ], "total": 12 }

grite issue show

{
  "issue": { "...": "IssueSummary" },
  "events": [ { "...": "Event" } ]
}

grite sync

{
  "pulled": true,
  "pushed": true,
  "wal_head": "<git-commit-hash>",
  "remote_wal_head": "<git-commit-hash>"
}

grite doctor

{
  "checks": [
    { "id": "wal_ref", "status": "ok|warn|error", "message": "...", "plan": ["..."] }
  ],
  "applied": [ "rebuild", "fetch" ]
}

grite rebuild

{
  "wal_head": "<git-commit-hash>",
  "event_count": 1234,
  "from_snapshot": "refs/grite/snapshots/1700000000000"
}

grite db stats

{
  "path": ".git/grite/actors/<actor_id>/sled",
  "size_bytes": 1234567,
  "event_count": 1234,
  "issue_count": 12,
  "last_rebuild_ts": 1700000000000,
  "events_since_rebuild": 42,
  "days_since_rebuild": 3,
  "rebuild_recommended": false
}

grite db check

{
  "events_checked": 1234,
  "events_valid": 1234,
  "corrupt_count": 0,
  "errors": []
}

grite db verify

{
  "events_checked": 1234,
  "signatures_checked": 1000,
  "signatures_valid": 1000,
  "error_count": 0,
  "errors": []
}

grite export

{
  "format": "json|md",
  "output_path": ".grite/export.json",
  "wal_head": "<git-commit-hash>",
  "event_count": 1234
}

grite snapshot

{
  "snapshot_ref": "refs/grite/snapshots/1700000000000",
  "wal_head": "<git-commit-hash>",
  "event_count": 1234
}

grite snapshot gc

{ "deleted": ["refs/grite/snapshots/1690000000000"] }

grite lock acquire|renew|release

{
  "lock": {
    "resource": "path:docs/cli.md",
    "owner": "<actor_id>",
    "nonce": "<random>",
    "expires_unix_ms": 1700000000000
  }
}

grite lock status

{
  "locks": [ { "...": "lock" } ],
  "conflicts": [ { "resource": "...", "owner": "...", "expires_unix_ms": 1700000000000 } ]
}

grite lock gc

{ "expired_pruned": 3 }

grite daemon status

{
  "daemon": {
    "running": true,
    "pid": 12345,
    "endpoint": "/tmp/grite-daemon.sock",
    "workers": [
      { "repo_root": "/path/to/repo", "actor_id": "...", "data_dir": "..." }
    ]
  }
}

grite daemon stop

{ "stopped": true }

grite context index

{
  "indexed": 42,
  "skipped": 15,
  "total_files": 57
}

grite context query

{
  "query": "Config",
  "matches": [
    { "symbol": "Config", "path": "src/config.rs" }
  ],
  "count": 1
}

grite context show

{
  "path": "src/main.rs",
  "language": "rust",
  "summary": "rust file with 2 functions: main, setup",
  "content_hash": "a1b2c3d4...",
  "symbols": [
    { "name": "main", "kind": "function", "line_start": 1, "line_end": 10 }
  ],
  "symbol_count": 1
}

grite context project

{
  "entries": [
    { "key": "api_version", "value": "v2" }
  ],
  "count": 1
}

grite context project <key>

{
  "key": "api_version",
  "value": "v2"
}

grite context set

{
  "key": "api_version",
  "value": "v2",
  "action": "set"
}