native macOS codings agent orchestrator
Merge pull request #90 from onevcat/onevpaw/issue-65-cli-list-output-contract
docs(cli): define JSON contract for prowl list
+212
+212
doc-onevcat/contracts/cli/list.md
+212
doc-onevcat/contracts/cli/list.md
···
1
+
# CLI Contract: `prowl list`
2
+
3
+
Status: draft truth source for `#65`.
4
+
5
+
This file defines the **JSON output contract** for:
6
+
7
+
- `prowl list --json`
8
+
9
+
Non-JSON `prowl list` remains human-readable text and is intentionally outside this file.
10
+
11
+
## Contract goals
12
+
13
+
- JSON output is **pane-oriented**: one array item per actionable pane.
14
+
- The payload must expose enough information for follow-up commands such as `focus`, `send`, `key`, and `read`.
15
+
- IDs must be stable within the current running instance and must be returned as strings.
16
+
17
+
## Success payload
18
+
19
+
```json
20
+
{
21
+
"ok": true,
22
+
"command": "list",
23
+
"schema_version": "prowl.cli.list.v1",
24
+
"data": {
25
+
"count": 2,
26
+
"items": [
27
+
{
28
+
"worktree": {
29
+
"id": "Prowl:/Users/onevcat/Projects/Prowl",
30
+
"name": "Prowl",
31
+
"path": "/Users/onevcat/Projects/Prowl",
32
+
"root_path": "/Users/onevcat/Projects/Prowl",
33
+
"kind": "git"
34
+
},
35
+
"tab": {
36
+
"id": "2FC00CF0-3974-4E1B-BEF8-7A08A8E3B7C0",
37
+
"title": "Prowl 1",
38
+
"selected": true
39
+
},
40
+
"pane": {
41
+
"id": "6E1A2A10-D99F-4E3F-920C-D93AA3C05764",
42
+
"title": "zsh",
43
+
"cwd": "/Users/onevcat/Projects/Prowl",
44
+
"focused": true
45
+
},
46
+
"task": {
47
+
"status": "running"
48
+
}
49
+
},
50
+
{
51
+
"worktree": {
52
+
"id": "Notes:/Users/onevcat/Projects/Notes",
53
+
"name": "Notes",
54
+
"path": "/Users/onevcat/Projects/Notes",
55
+
"root_path": "/Users/onevcat/Projects/Notes",
56
+
"kind": "plain"
57
+
},
58
+
"tab": {
59
+
"id": "A2B07BBA-9DD0-4C77-9D76-2B3E0AF12096",
60
+
"title": "Notes",
61
+
"selected": false
62
+
},
63
+
"pane": {
64
+
"id": "EF65FF31-1B72-40B2-80DA-3AA87B7B6858",
65
+
"title": "Notes",
66
+
"cwd": "/Users/onevcat/Projects/Notes",
67
+
"focused": false
68
+
},
69
+
"task": {
70
+
"status": "idle"
71
+
}
72
+
}
73
+
]
74
+
}
75
+
}
76
+
```
77
+
78
+
## Required top-level fields
79
+
80
+
- `ok`: boolean, must be `true` on success.
81
+
- `command`: string, must be `"list"`.
82
+
- `schema_version`: string, currently `"prowl.cli.list.v1"`.
83
+
- `data`: object.
84
+
85
+
## `data` fields
86
+
87
+
- `count`: integer, must equal `items.length`.
88
+
- `items`: array of pane rows.
89
+
90
+
## Pane row shape
91
+
92
+
Every item in `data.items` represents exactly one actionable pane.
93
+
94
+
### `worktree`
95
+
96
+
- `id`: string
97
+
- `name`: string
98
+
- `path`: string, absolute path to the worktree or plain folder shown in the UI
99
+
- `root_path`: string, absolute repository root or plain-folder root
100
+
- `kind`: `"git"` | `"plain"`
101
+
102
+
### `tab`
103
+
104
+
- `id`: string, UUID text form
105
+
- `title`: string
106
+
- `selected`: boolean
107
+
108
+
### `pane`
109
+
110
+
- `id`: string, UUID text form
111
+
- `title`: string
112
+
- `cwd`: string or `null`
113
+
- `focused`: boolean
114
+
115
+
### `task`
116
+
117
+
- `status`: `"idle"` | `"running"` | `null`
118
+
- `null` is allowed when runtime state is unavailable for that pane/worktree.
119
+
120
+
## Output invariants
121
+
122
+
- `tab.selected == true` means the row's tab is the currently selected tab of that worktree.
123
+
- `pane.focused == true` means the row is the current focused pane within its selected tab.
124
+
- At most one row in the whole payload should have `pane.focused == true`.
125
+
- A worktree with split panes returns multiple rows that share the same `worktree` and `tab` objects but differ in `pane`.
126
+
- The array order should be stable for a single call. Preferred order: worktree order, then tab order, then pane order.
127
+
128
+
## Error payload
129
+
130
+
```json
131
+
{
132
+
"ok": false,
133
+
"command": "list",
134
+
"schema_version": "prowl.cli.list.v1",
135
+
"error": {
136
+
"code": "APP_NOT_RUNNING",
137
+
"message": "Prowl is not running"
138
+
}
139
+
}
140
+
```
141
+
142
+
## Error codes for v1
143
+
144
+
- `APP_NOT_RUNNING`
145
+
- `LIST_FAILED`
146
+
147
+
## Notes
148
+
149
+
- `list --json` is the discovery primitive for all later target-based commands.
150
+
- `cwd` should be the best available runtime working directory for the pane; when unavailable it must be `null`, not an invented fallback string.
151
+
- `task.status` is intentionally coarse in v1 because the parent issue only requires “running status (if available)”.
152
+
153
+
## Example: split tab
154
+
155
+
```json
156
+
{
157
+
"ok": true,
158
+
"command": "list",
159
+
"schema_version": "prowl.cli.list.v1",
160
+
"data": {
161
+
"count": 2,
162
+
"items": [
163
+
{
164
+
"worktree": {
165
+
"id": "Prowl:/Users/onevcat/Projects/Prowl",
166
+
"name": "Prowl",
167
+
"path": "/Users/onevcat/Projects/Prowl",
168
+
"root_path": "/Users/onevcat/Projects/Prowl",
169
+
"kind": "git"
170
+
},
171
+
"tab": {
172
+
"id": "2FC00CF0-3974-4E1B-BEF8-7A08A8E3B7C0",
173
+
"title": "Prowl 1",
174
+
"selected": true
175
+
},
176
+
"pane": {
177
+
"id": "6E1A2A10-D99F-4E3F-920C-D93AA3C05764",
178
+
"title": "build",
179
+
"cwd": "/Users/onevcat/Projects/Prowl",
180
+
"focused": true
181
+
},
182
+
"task": {
183
+
"status": "running"
184
+
}
185
+
},
186
+
{
187
+
"worktree": {
188
+
"id": "Prowl:/Users/onevcat/Projects/Prowl",
189
+
"name": "Prowl",
190
+
"path": "/Users/onevcat/Projects/Prowl",
191
+
"root_path": "/Users/onevcat/Projects/Prowl",
192
+
"kind": "git"
193
+
},
194
+
"tab": {
195
+
"id": "2FC00CF0-3974-4E1B-BEF8-7A08A8E3B7C0",
196
+
"title": "Prowl 1",
197
+
"selected": true
198
+
},
199
+
"pane": {
200
+
"id": "1344AEF5-3BA6-4B75-A07E-1F36C63A34B0",
201
+
"title": "tests",
202
+
"cwd": "/Users/onevcat/Projects/Prowl",
203
+
"focused": false
204
+
},
205
+
"task": {
206
+
"status": "idle"
207
+
}
208
+
}
209
+
]
210
+
}
211
+
}
212
+
```