Proposal for lstk JSON output schema#374
Draft
peter-smith-phd wants to merge 4 commits into
Draft
Conversation
peter-smith-phd
changed the title
lstk JSON output schema
peter-smith-phd
added
semver: minor
docs: needed
Checkpoint before implementation: proposal, design, specs, and tasks for a standardized JSON envelope, error-code taxonomy, and per-command output schema across lstk's --json flag, informed by prior art (Kubernetes, Terraform, GitHub CLI, Docker, AWS CLI, JSON-RPC 2.0) and naming choices that anticipate future YAML support. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…eset/update Implements the shared envelope/error-code contract from the json-output-schema proposal and wires --json support through stop, reset, and update as a pilot, to validate the design before rolling it out to the rest of the command surface. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
requireJSONSupport now renders an unsupported command's --json rejection as a JSON envelope on stdout (error.code: NOT_JSON_CAPABLE) instead of plain text on stderr, but these tests still asserted the old stderr-based contract from the earlier add-json-flag PR. Update them to decode the envelope and assert against it instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Rebased onto main, which removed the deprecated `lstk config profile` command (#360) — it no longer exists, so it shouldn't be listed as a command that "will never support --json". Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
peter-smith-phd
force-pushed
the
devx-956-json-output-standard
branch
from
1ad7edc to
593101b
Compare
skyrpex
approved these changes
Jul 9, 2026
skyrpex
left a comment
skyrpex
left a comment
Contributor
There was a problem hiding this comment.
Looks good to me, specially the logs streaming using NDJSON :) Nice job.
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
2 participants
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.
Summary
This PR is primarily a review of the
lstkJSON output schema design. The main thing to review isdocs/structured-output.md, containing the detailed specification of how the JSON output fromlstkshould be structured. This is a proposal, but as soon as we solidify the design it'll be locked in (e.g. we can't iterate without changing the schema version number).This includes:
To prove this all works, three commands (
stop,reset,update) are wired up end-to-end with--jsonas a pilot. These were chosen as simple commands that could exercise the new schema, and give a feel for how it looks.Additionally, the docs/structured-output.md` proposes but doesn't solidify the details for all the other commands. We can revisit these schemas when we actually add JSON support for each command (in later PRs).
If you do nothing else, please read
docs/structured-output.md