CLI Standard v1.1.0 — diagnostic severity ladder, machine envelope, unified rendering - #35
Conversation
…1.1.0
Adds references/diagnostics.md: the [ERROR]/[WARN]/[OK]/[INFO] severity
ladder (§18.2.1 tags; hint is a field, never a severity), message style
rules, the single-line {"diagnostic":{...}} stderr envelope for
non-error severities (error envelope unchanged; ad-hoc {"warning":...}
deprecated), the --quiet/--verbose/agent severity floor, unified
[TAG]-first human rendering via §11.1 theme tokens, and a non-normative
CI-annotation downcast table.
Conforming edits: SKILL.md (masthead v1.1.0, §1 row 8, §2 rule 5, §3
floor-defined --quiet/--verbose, §7 routing row), exit-codes-errors.md §6
tagged render, output-modes.md §2 token mapping + §6 FORCE_COLOR-before-
NO_COLOR fix (self-contradiction; force-color.org order) + §7,
tui-explore.md diagnostic-envelope fallback, rust-implementation.md
Severity/Diagnostic sketches, testing-compliance.md matrix rows 28-31.
spacecraft-agentic-cli: §3 hint-is-a-field, §4 verbosity as named floors,
tips-thinking.md §6 unified render (resolves Error:/→ Try: conflict),
error-hint-catalog.json nix-shell -p → nix run (stale vs tips-thinking).
New references/CHANGELOG.md holds the version history. Both skills'
bundles rebuilt in this commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4e3f6c629d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # Spacecraft Software CLI Standard — Dual-Mode Self-Documenting CLI Framework | ||
|
|
||
| **Version:** 1.0.0 | **Spec Date:** 2026-04-10 | **Author:** Mohamed Hammad | ||
| **Version:** 1.1.0 | **Spec Date:** 2026-08-10 | **Author:** Mohamed Hammad |
There was a problem hiding this comment.
The raw e23bfab commit object has no gpgsig header, and git show --show-signature reports no signature. This release commit therefore cannot receive the required Verified status; recreate it with the repository-configured signing key before landing.
AGENTS.md reference: AGENTS.md:L29-L30
Useful? React with 👍 / 👎.
| // Tag colored via theme token; message in default foreground. | ||
| eprintln!("{} {}", self.severity.tag(), self.message); |
There was a problem hiding this comment.
When human mode has color enabled, this new reference implementation still prints the tag and hint as plain text: it never consults mode.color_enabled() or applies the severity theme token. Implementers copying this concrete scaffold will therefore violate the new diagnostics.md §5 color contract for every non-error diagnostic, even though the adjacent comment claims the tag is colored.
Useful? React with 👍 / 👎.
| #[derive(Debug, Serialize, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] | ||
| #[serde(rename_all = "lowercase")] | ||
| pub enum Severity { Info, Ok, Warn, Error } |
There was a problem hiding this comment.
If an implementer constructs the public Diagnostic with Severity::Error, this scaffold serializes a forbidden {"diagnostic":{"severity":"error",...}} object without the required exit_code, rather than routing through AppError. The comment alone does not enforce the envelope invariant; use a non-error-only severity type for Diagnostic or otherwise prevent Error from being serialized through it.
Useful? React with 👍 / 👎.
#36) Implements the diagnostics spec (references/diagnostics.md, PR #35): - New output/diagnostic.rs: Severity ladder (Info < Ok < Warn < Error, §18.2.1 tags), Diagnostic type emitting single-line {"diagnostic":{...}} envelopes in machine mode and [TAG]-first human rendering, gated by the severity floor on Context (--quiet → errors only, agent env → warn+, default → ok+, --verbose → info+). Errors (AppError) never consult the floor. - error.rs human render: error:/hint: → [ERROR] tag + indented hint:, tag carried in the colorless branch too (color is never the sole carrier of meaning). - mode.rs: warn_tui_fallback deleted — resolve() now returns the fallback reason and main emits a TUI_FALLBACK warn diagnostic after Context exists (no more raw JSON on a human TTY; drops the non-spec fell_back_to field). FORCE_COLOR now checked before NO_COLOR so it overrides it (was inverted vs its own comment and the spec). - theme.rs migrated from the grandfathered v1.33 six-token palette to the eleven Steelbore 2 §11.1 role tokens (this is the "next minor release" the grandfathering clause named); render.rs and tui/mod.rs remapped per tui-explore.md §3. - sync.rs nix progress passthrough gated by the info floor; ship.rs oversized-description hint and tui/mod.rs fallback hint made paste-test-clean runnable commands. - Tests: floor table, envelope shape/single-line/hint-omission, tag presence with and without color, FORCE_COLOR-over-NO_COLOR, agent-env explore fallback parses as a warn diagnostic, --quiet suppresses the fallback but never errors. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 participant
What
Adds normative error/feedback message design to
spacecraft-cli-standard(bumped v1.0.0 → v1.1.0), making every CLI message simultaneously machine-friendly for AI agents and human-friendly with color-coded severity.New:
references/diagnostics.md[ERROR][WARN][OK][INFO].hintis a field on any diagnostic, never a severity (rustc's rule: the message states what happened; only the hint suggests the fix — and the hint stays a paste-test-clean runnable command).{"error":{...}}object is unchanged; non-error severities get{"diagnostic":{severity, code, message, hint?, timestamp, command, ...}}— single-line JSONL on stderr, never stdout. The one-off{"warning":{...}}TUI-fallback shape is deprecated.--quiet= errors only; agent env (AI_AGENT/AGENT) =warn+ (failures + degradations — the TUI-fallback warning the compliance matrix requires still reaches agents, whileok/infotoken chatter is suppressed); default =ok+;--verbose=info+.[TAG] message+ indentedhint:/docs:lines, colored via §11.1 theme tokens (error/warning/success/structure/accent). Tags surviveNO_COLOR/colorless/accessible modes — color is never the sole carrier of meaning (§18.2.1). Resolves the pre-existing render conflict betweenexit-codes-errors.md§6 (error:) and agentic-clitips-thinking.md§6 (Error:/→ Try:).Normative fix folded in
output-modes.md§6 listedNO_COLORbeforeFORCE_COLORunder "first match decides" while also sayingFORCE_COLOR"overrides NO_COLOR" — self-contradictory. ReorderedFORCE_COLORfirst (force-color.org; the reference Rust sketch already checked in that order).Conforming edits
SKILL.md (§1 row 8, §2 rule 5, §3
--quiet/--verboseas floor settings, §7 routing, masthead + changelog pointer),exit-codes-errors.md,tui-explore.md,rust-implementation.md(addsSeverity/Diagnosticsketches + tag-emittingemit_human),testing-compliance.md(matrix rows 28–31), newreferences/CHANGELOG.md. spacecraft-agentic-cli: §3 hint-is-a-field, §4 verbosity tied to named floors,tips-thinking.md§6 unified layout,error-hint-catalog.jsonnix-shell -p→nix run nixpkgs#(was contradicted by its own reference file). README catalogue row updated. Both skills' bundles rebuilt in the same commit.Prior art researched
rustc diagnostics (
--error-format=json, severity+code,rendered), clap/cargo, Elm, GCC/Clang (GCC_COLORS, fix-its), SARIF 2.1.0, ESLint, GitHub/Azure CI annotations, clig.dev, NO_COLOR/FORCE_COLOR specs, and published agent-friendly-CLI guidance (Anthropic, Speakeasy).Notes for the maintainer
spacecraft-agentic-cli/SKILL.md) and Sync §17 labelled-row progress block — Standard v1.47 #34 — those branches also carry un-rebuilt agentic-cli bundles; whichever merges second should re-run the drift sweep.construct-clicompliance —Diagnostictype,[TAG]rendering, severity floor,warn_tui_fallbacknormalization,FORCE_COLORorder fix, Steelbore 2 theme migration.check-skill-refs.py(no version pins), catalog JSON validity, full bundle drift sweep clean.🤖 Generated with Claude Code