Repository navigation
fix: say the CLI's user-visible text in plain English - #71
Merged
Merged
Conversation
grubmeshi
marked this pull request as ready for review
November 6, 2026 10:25
|
Coverage of the acceptance run against the meshStack backend, on
No unit coverage. The satellite's unit test job published no covdata-unit artifact for this commit, so the figures cover the acceptance half only. Uncovered functions
|
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The tests can produce false positives by accepting unrelated endpoint-prompt errors instead of verifying the profile lock and checking a callback hostname that does not distinguish successful authentication from failure.
2 open issues
What changed in this PR
This PR makes meshStack CLI help, prompts, errors, and logs easier to understand, while aiming to preserve command behavior.
Changes:
- Rewrites user-facing text and standardizes workspace guidance, command references, and validation messages.
- Updates unit-test expectations and makes acceptance assertions less dependent on exact wording.
- Refreshes the CLI usage guide to match the revised workspace-role error.
| File | Description |
|---|---|
| skills/meshstack-cli/SKILL.md | Updates the quoted workspace-role error. |
| internal/tfstate/proxy.go | Clarifies state-validation errors and lock warnings. |
| internal/tfstate/proxy_test.go | Updates expected errors and warnings. |
| internal/tfstate/lock.go | Clarifies lock ownership and release errors. |
| internal/tfstate/buildingblock.go | Clarifies run-related state-write refusals. |
| internal/setting/resolve.go | Clarifies setting-override warnings. |
| internal/setting/resolve_test.go | Updates override-warning expectations. |
| internal/profile/select.go | Clarifies ambiguous profile selection. |
| internal/profile/name.go | Simplifies profile precedence documentation. |
| internal/oidc/browser/browser.go | Clarifies unsupported access-level errors. |
| internal/meshstack/workspaces.go | Clarifies inaccessible default-workspace warnings. |
| internal/meshstack/workspace.go | Simplifies workspace and role errors. |
| internal/meshstack/settings.go | Clarifies version-check setting help. |
| internal/auth/status_test.go | Updates credential-warning expectations. |
| internal/auth/session.go | Adds clearer endpoint-mismatch recovery guidance. |
| internal/auth/session_test.go | Updates setting-warning expectations. |
| internal/auth/credentials.go | Standardizes credential warnings and login hints. |
| internal/auth/credential/oidclogin.go | Clarifies workspace selection guidance. |
| internal/auth/credential_manual.go | Simplifies access-token documentation. |
| internal/auth/cache.go | Uses the long profile flag in login hints. |
| internal/auth/cache_test.go | Updates the cache-warning expectation. |
| cmd/workspace/list.go | Simplifies workspace visibility help. |
| cmd/profile/store.go | Clarifies profile-lock and selection messages. |
| cmd/profile/store_test.go | Updates profile-warning expectations. |
| cmd/profile/show.md.tmpl | Simplifies profile status and login guidance. |
| cmd/profile/show.go | Clarifies profile display help and warnings. |
| cmd/profile/show_test.go | Updates display and warning expectations. |
| cmd/profile/select_profile.go | Simplifies endpoint-selection errors. |
| cmd/profile/profile.go | Clarifies profile management help. |
| cmd/profile/profile_test.go | Updates prompt and error expectations. |
| cmd/profile/model.go | Simplifies deletion and cancellation messages. |
| cmd/profile/model_test.go | Updates profile-warning expectations. |
| cmd/profile/form.go | Revises endpoint and workspace field descriptions. |
| cmd/profile/edit.go | Simplifies profile editing instructions. |
| cmd/profile/delete.go | Clarifies deletion confirmation requirements. |
| cmd/profile/add.go | Simplifies profile creation instructions. |
| cmd/internal/testacc/tfstate_test.go | Loosens text assertions and checks locks through errors. |
| cmd/internal/testacc/profile_test.go | Reduces dependence on full profile messages. |
| cmd/internal/testacc/login_test.go | Revises login outcome assertions. |
| cmd/internal/testacc/buildingblockrun_test.go | Checks failed runs by UUID. |
| cmd/internal/testacc/api_test.go | Checks stable API error values and hints. |
| cmd/internal/read.go | Clarifies JSON input errors. |
| cmd/internal/prompt/prompt.go | Simplifies the end-of-input error. |
| cmd/internal/prompt/prompt_test.go | Updates prompt-error expectations. |
| cmd/internal/prompt/model.go | Simplifies selection keyboard guidance. |
| cmd/internal/output.go | Standardizes output-format help and errors. |
| cmd/internal/markdown/markdown_test.go | Updates credential display expectations. |
| cmd/internal/markdown/credential.md.tmpl | Simplifies token messages and login hints. |
| cmd/internal/list.go | Clarifies invalid-limit errors. |
| cmd/internal/list_test.go | Updates invalid-limit expectations. |
| cmd/internal/buildingblock/run_wait.go | Clarifies paused-run errors. |
| cmd/eventlog/list.go | Simplifies listing help and date errors. |
| cmd/eventlog/list_test.go | Updates date-error expectations. |
| cmd/buildingblockrun/logs.go | Clarifies log-following help and errors. |
| cmd/buildingblockrun/logs_test.go | Updates unknown-status expectations. |
| cmd/buildingblockrun/list.go | Simplifies run-listing scope help. |
| cmd/buildingblockdefinitionversion/list.go | Clarifies required definition and permission help. |
| cmd/buildingblockdefinition/list.go | Simplifies definition visibility help. |
| cmd/buildingblock/wait.go | Clarifies waiting behavior and input errors. |
| cmd/buildingblock/wait_test.go | Updates paused-run expectations. |
| cmd/buildingblock/trigger_run.go | Clarifies triggering help and run messages. |
| cmd/buildingblock/tfstate/tfstate.go | Simplifies state permissions and backend guidance. |
| cmd/buildingblock/tfstate/tfstate_test.go | Updates state-command message expectations. |
| cmd/buildingblock/tfstate/show.go | Clarifies state output and workspace selection. |
| cmd/buildingblock/tfstate/force_unlock.go | Simplifies stale-lock help and confirmation text. |
| cmd/buildingblock/tfstate/exec.go | Rewrites execution help, warnings, and flag descriptions. |
| cmd/buildingblock/list.go | Simplifies building-block visibility help. |
| cmd/buildingblock/buildingblock.go | Clarifies the terminal requirement. |
| cmd/buildingblock/approve_run.go | Simplifies approval help, prompts, and errors. |
| cmd/buildingblock/approve_run_internal_test.go | Updates the terminal-error expectation. |
| cmd/buildingblock/abort_run.go | Clarifies abort help and refusal errors. |
| cmd/auth/token.go | Simplifies access-token usage help. |
| cmd/auth/stdin.go | Simplifies empty-secret errors. |
| cmd/auth/status.go | Clarifies credential status and renewal help. |
| cmd/auth/select_workspace.go | Simplifies workspace selection messages. |
| cmd/auth/select_profile.go | Clarifies profile selection and recovery hints. |
| cmd/auth/logout.go | Simplifies logout help and warnings. |
| cmd/auth/login.go | Clarifies login help and input errors. |
| cmd/auth/login_test.go | Updates selection-error expectations. |
| cmd/api/request.go | Clarifies request flags and validation errors. |
| cmd/api/profile.go | Simplifies endpoint-matching messages. |
| cmd/api/profile_test.go | Updates endpoint-error expectations. |
| cmd/api/docs.go | Clarifies API documentation help and errors. |
| cmd/api/describe.go | Standardizes unknown-kind and action errors. |
| cmd/api/api.go | Simplifies request help and fallback warnings. |
| cmd/api/api_test.go | Updates API message expectations. |
Review effort: Balanced
henryde
requested changes
Nov 6, 2026
The same thing is now said the same way across commands, for example "Use --workspace to choose another workspace". Commands in error and log text are quoted with single quotes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The tests check the exit status, the error value and key values such as UUIDs and profile names, so that a reworded message does not break them. The lock tests check profile.ErrInUse, and the browser login requires HTTP 200 from the callback. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Help wraps to the terminal, up to 100 columns, and to 80 in a pipe. The help texts have no line breaks inside a paragraph any more. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The development skill holds the help-text rules. Help and messages build flag names from the flag definitions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
grubmeshi
force-pushed
the
fix/plain-cli-texts
branch
from
November 6, 2026 14:09
637216f to
c3dbd30
Compare
|
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
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.
Rewrites the user-visible text of the CLI in plain English: command help, flag help, form text, error messages and log messages. The meaning stays the same.
cmd/internal.'meshstack …'. Markdown output keeps backticks.--outputhelp, "is not a valid X; use A or B", the hints to log in again, and the errors when a profile does not match the endpoint.tfstate execgets a rewritten help text with the same facts.skills/meshstack-cli/SKILL.mdquotes the new "you need a role in that workspace" error.The acceptance tests now check only the exit status and key values such as UUIDs, profile names, actions, and command and flag names. They no longer check full sentences. The lock tests check
profile.ErrInUse, and the browser login test requires HTTP 200 from the callback, so later text changes do not break them. Assertions on tofu, Keycloak and JSON output are unchanged.requireNoLocknow checks for no lock through the exit status of force-unlock.Help now wraps to the terminal width, up to 100 columns, and 80 in a pipe. The help texts have no line breaks inside paragraphs. Flag names in help and messages come from the flag definitions.
The
developmentskill has a new style guide for help text, errors and log messages (help-textrules), and the last commit applies it to every command.Each commit covers one area, so you can drop one if you disagree with it.
Testing
task lintandtask testpass on every commit.🤖 Generated with Claude Code