docs: update README for --fields, elapsed_ms, error actions, exit code 19
Documents the robot mode enhancements from the previous commits: - Field selection (--fields flag and minimal preset) with examples and complete field lists for issues and MRs - Updated response format section to show meta.elapsed_ms and compact single-line JSON - Error actions array with recovery shell commands - Agent self-discovery section explaining robot-docs response_schema - Exit code 19 for health check failure added to the table Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
54
README.md
54
README.md
@@ -177,9 +177,13 @@ lore issues --has-due # Only issues with due dates
|
|||||||
lore issues -p group/repo # Filter by project
|
lore issues -p group/repo # Filter by project
|
||||||
lore issues --sort created --asc # Sort by created date, ascending
|
lore issues --sort created --asc # Sort by created date, ascending
|
||||||
lore issues -o # Open first result in browser
|
lore issues -o # Open first result in browser
|
||||||
|
|
||||||
|
# Field selection (robot mode)
|
||||||
|
lore -J issues --fields minimal # Compact: iid, title, state, updated_at_iso
|
||||||
|
lore -J issues --fields iid,title,labels,state # Custom fields
|
||||||
```
|
```
|
||||||
|
|
||||||
When listing, output includes: IID, title, state, author, assignee, labels, and update time.
|
When listing, output includes: IID, title, state, author, assignee, labels, and update time. In robot mode, the `--fields` flag controls which fields appear in the JSON response.
|
||||||
|
|
||||||
When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions.
|
When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions.
|
||||||
|
|
||||||
@@ -220,6 +224,10 @@ lore mrs --since 7d # Updated in last 7 days
|
|||||||
lore mrs -p group/repo # Filter by project
|
lore mrs -p group/repo # Filter by project
|
||||||
lore mrs --sort created --asc # Sort by created date, ascending
|
lore mrs --sort created --asc # Sort by created date, ascending
|
||||||
lore mrs -o # Open first result in browser
|
lore mrs -o # Open first result in browser
|
||||||
|
|
||||||
|
# Field selection (robot mode)
|
||||||
|
lore -J mrs --fields minimal # Compact: iid, title, state, updated_at_iso
|
||||||
|
lore -J mrs --fields iid,title,draft,target_branch # Custom fields
|
||||||
```
|
```
|
||||||
|
|
||||||
When listing, output includes: IID, title (with [DRAFT] prefix if applicable), state, author, assignee, labels, and update time.
|
When listing, output includes: IID, title (with [DRAFT] prefix if applicable), state, author, assignee, labels, and update time.
|
||||||
@@ -412,7 +420,7 @@ lore version
|
|||||||
|
|
||||||
## Robot Mode
|
## Robot Mode
|
||||||
|
|
||||||
Machine-readable JSON output for scripting and AI agent consumption.
|
Machine-readable JSON output for scripting and AI agent consumption. All responses use compact (single-line) JSON with a uniform envelope and timing metadata.
|
||||||
|
|
||||||
### Activation
|
### Activation
|
||||||
|
|
||||||
@@ -432,18 +440,51 @@ lore issues -n 5 | jq .
|
|||||||
|
|
||||||
### Response Format
|
### Response Format
|
||||||
|
|
||||||
All commands return consistent JSON:
|
All commands return a consistent JSON envelope to stdout:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{"ok": true, "data": {...}, "meta": {...}}
|
{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
|
||||||
```
|
```
|
||||||
|
|
||||||
Errors return structured JSON to stderr:
|
Every response includes `meta.elapsed_ms` (wall-clock milliseconds for the command).
|
||||||
|
|
||||||
|
Errors return structured JSON to stderr with machine-actionable recovery steps:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{"error": {"code": "CONFIG_NOT_FOUND", "message": "...", "suggestion": "Run 'lore init'"}}
|
{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
The `actions` array contains executable shell commands an agent can run to recover from the error. It is omitted when empty (e.g., for generic I/O errors).
|
||||||
|
|
||||||
|
### Field Selection
|
||||||
|
|
||||||
|
The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response, reducing token usage for AI agent workflows:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Minimal preset (~60% fewer tokens)
|
||||||
|
lore -J issues --fields minimal
|
||||||
|
|
||||||
|
# Custom field list
|
||||||
|
lore -J issues --fields iid,title,state,labels,updated_at_iso
|
||||||
|
|
||||||
|
# Available presets
|
||||||
|
# minimal: iid, title, state, updated_at_iso
|
||||||
|
```
|
||||||
|
|
||||||
|
Valid fields for issues: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`
|
||||||
|
|
||||||
|
Valid fields for MRs: `iid`, `title`, `state`, `author_username`, `labels`, `draft`, `target_branch`, `source_branch`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `reviewers`
|
||||||
|
|
||||||
|
### Agent Self-Discovery
|
||||||
|
|
||||||
|
The `robot-docs` command provides a complete machine-readable manifest including response schemas for every command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
lore robot-docs | jq '.data.commands.issues.response_schema'
|
||||||
|
```
|
||||||
|
|
||||||
|
Each command entry includes `response_schema` describing the shape of its JSON response, `fields_presets` for commands supporting `--fields`, and copy-paste `example` invocations.
|
||||||
|
|
||||||
### Exit Codes
|
### Exit Codes
|
||||||
|
|
||||||
| Code | Meaning |
|
| Code | Meaning |
|
||||||
@@ -467,6 +508,7 @@ Errors return structured JSON to stderr:
|
|||||||
| 16 | Embedding failed |
|
| 16 | Embedding failed |
|
||||||
| 17 | Not found (entity does not exist) |
|
| 17 | Not found (entity does not exist) |
|
||||||
| 18 | Ambiguous match (use `-p` to specify project) |
|
| 18 | Ambiguous match (use `-p` to specify project) |
|
||||||
|
| 19 | Health check failed |
|
||||||
| 20 | Config not found |
|
| 20 | Config not found |
|
||||||
|
|
||||||
## Configuration Precedence
|
## Configuration Precedence
|
||||||
|
|||||||
Reference in New Issue
Block a user