Skip to content

fix(cli): keep help and schema examples consistent#71

Draft
jo-hnny wants to merge 1 commit into
TencentCloudAgentRuntime:mainfrom
jo-hnny:codex/issue-46-help-schema-consistency
Draft

fix(cli): keep help and schema examples consistent#71
jo-hnny wants to merge 1 commit into
TencentCloudAgentRuntime:mainfrom
jo-hnny:codex/issue-46-help-schema-consistency

Conversation

@jo-hnny

@jo-hnny jo-hnny commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Parse the final Cobra Example blocks back into command examples and use them to populate CommandSchema.Examples.
  • Initialize and include Cobra's special help command when building the schema catalog.
  • Add regression coverage for multi-line examples and a gate that keeps every public leaf command's help and schema examples aligned.

Related to #46.

Root cause

Command examples could come from generated descriptors, handwritten Cobra commands, Long help text, or the default example fallback. Text help used the final Cobra command tree, while the schema catalog only copied examples from selected descriptor metadata. As a result, examples visible in help were missing from machine-readable schema output.

External impact

  • Plain-text --help, agr help, and text-mode agr schema output are unchanged.
  • agr schema ... -o json and --help -o json now expose existing help examples for 37 additional commands.
  • Leaf-command example coverage increases from 5/42 to 42/42.
  • Command ordering, non-example schema fields, exit codes, command execution, and flag parsing are unchanged.
  • This populates the existing Examples field in agr.v1; it does not introduce a new schema field. Consumers using exact JSON snapshots will observe the additional values.

Benefits

  • Keeps human-readable help and machine-readable schema consistent from the same final Cobra command state.
  • Makes more realistic usage examples available to LLMs and other schema consumers.
  • Prevents future commands from silently drifting through an all-command regression gate.
  • Reuses existing example definitions instead of duplicating them in handwritten schema metadata.

Validation

  • go test ./... -count=1
  • go run ./cmd/internal/cobragen check
  • git diff --check
  • Compared pre-change and post-change CLI output: all 52 command help pages and root text help are unchanged; only Examples values differ in JSON schema/help output.

@jo-hnny
jo-hnny requested a review from keithfx999 July 14, 2026 11:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant