feat: add --json structured output to runtime observability (CH-004)#3
Merged
Conversation
…(CH-004)
Add an opt-in `--json` flag to `gogents runtime list` and `gogents runtime
status`, giving the agent-manager adapter a stable machine-readable contract
instead of parsing the human-facing text layer.
- `runtime list --json`: JSON array of runtimes; `[]` when none registered.
- `runtime status <target> --json`: single flat JSON object; a zero
last_sync_at renders as "" (not 0001-01-01…) via StatusView.MarshalJSON.
- `--json` failures emit {"error":{"code,message}}` to stderr with a
classified code (runtime_not_found / state_not_found / internal) and a
non-zero exit; stdout carries no payload.
- `--json` is position-tolerant (before or after the target).
- Without `--json`, all existing text output and exit behavior is unchanged.
Docs (D08, R12, README, unit-tests.md) fold the JSON contract into the
observability design. Tests cover the list array/empty case, the status
object (down / empty strings / RFC3339), error-code classification, and
flag position tolerance.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
摘要
為
gogents runtime list/gogents runtime status加上 opt-in 的--json，提供 agent-manager (am) 轉接器一個穩定的機器可讀契約，取代逐行解析人類可讀顯示層（欄位增減／順序／時間格式變動不再無聲破壞解析）。變更來源：docs/changes/change-add-json-output.md（CH-004）。行為
runtime list --json：輸出 runtime 陣列 JSON；無註冊時輸出[]（非文字(no registered runtimes)）。runtime status <target> --json：輸出單一扁平 JSON 物件；last_sync_at零值輸出""（非0001-01-01…），經StatusView.MarshalJSON處理。--json失敗：stderr 輸出{"error":{"code","message"}}、非零 exit、stdout 無 payload；code分類為runtime_not_found/state_not_found/internal。--json位置容忍：旗標可在 target 前或後。--json時所有現行文字輸出與 exit 行為完全不變；logs不變。變更範圍
程式
internal/cli/query.go：RuntimeView加 json tag、StatusView.MarshalJSON、新 sentinelErrStateNotFound。internal/cli/cli.go：runRuntime加--json分支、extractBoolFlag（位置容忍）、printJSON、emitRuntimeError+newRuntimeErrorEnvelope（error→code 分類）。測試（
internal/cli/json_test.go）[]；D08-12 status flat 物件（down、空字串、RFC3339）；D08-13 三 code + envelope marshal；extractBoolFlag位置容忍。文件
docs/designs/D08-runtime-cli.md（§3.1/§3.4/§4/§6/§7）、docs/requirements/reqs/R12-runtime-observability.md、README.md、docs/tests/unit-tests.md。驗證
go build ./...✓、go test ./...全通過 ✓、golangci-lint run0 issues ✓list --json（有/空[]）、status --json（down、零值""、旗標前後）、錯誤（runtime_not_found/state_not_found走 stderr、stdout 無 payload、exit 1）、text 模式不變，皆正確。🤖 Generated with Claude Code