Improve novice UX: help, errors, colors, and actionable hints#27
Merged
Conversation
sjquant
changed the title
…ibrary guidance - `skul add --help` (and any `skul <cmd> --help`) now returns command-specific help text showing the command's arguments and options, instead of erroring - Global `skul --help` appends a Getting Started workflow and copy-paste examples - When no bundles are cached and a bundle lookup fails, the error message now tells the user exactly how to add their first bundle from a Git source https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
Not a common CLI pattern — keep --help concise. https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
- Unknown commands now suggest the closest match via Levenshtein distance (e.g. "skul sts" → Did you mean "status"?) - skul list with no cached bundles now shows how to add one - All dead-end messages (no bundles configured, bundle not found in active set, requires a Git repository) now include a follow-up action hint https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
- Add picocolors: bold headers, cyan bundle names, green for success
actions (Applied/Updated/Removed/Reset), yellow for DRY RUN prefix,
dim for hints and Cloned lines
- skul status: add "Run skul add <bundle> to get started" hint when
nothing is configured; color Materialized and Git Exclude fields
- skul remove: when bundle not found, show what IS configured instead
of a generic "run skul status" pointer
- skul update: distinguish "all local-only" from "all up to date" with
a specific message naming the local-only bundles
- Conflict resolution prompts: replace terse labels with consequence-
oriented descriptions ("Save with a different name", "Add a prefix
to avoid the conflict", "Skip this file")
https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
picocolors already disables colors when stdout is not a TTY or NO_COLOR is set. Also disable when SKUL_NO_TUI=1 since that signals an agent or scripting context where ANSI codes are noise. JSON output paths were already safe — they return before any pc.* calls. https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
When any bundle reports update-available, append: Run "skul update" to apply available updates. Also color bundle names cyan in check output, consistent with status. https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
- Move const pc after all imports (was incorrectly mid-import block) - Make pc a Proxy so isHeadlessMode() is evaluated lazily at call time rather than once at module load, fixing potential stale state in tests - Remove redundant localOnly.length > 0 guard (=== entries.length implies it) - Fix did-you-mean punctuation: Unknown command: "x", did you mean "y"? - Remove trailing periods added to new messages to match existing convention - Add writeBundleManifest/writeBundleFile helpers that accept undefined source - Add 5 new tests: per-command --help routing, typo suggestion (present and absent), local-only update message, remove hint listing configured bundles https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
…t helper - Remove trailing period from "Bundle not found in active set" hint in selectDesiredEntries to match the no-period convention across all messages - Remove writeBundleManifest from cli.test.ts — it was added but all callers were switched to writeManifest before merging, leaving it unused https://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7
sjquant
force-pushed
the
claude/improve-novice-ux-viEEY
branch
from
a4e65b9 to
a09693a
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
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
Across-the-board novice UX improvements to the CLI. All changes follow established patterns from well-known CLIs (
gh,cargo,npm).Help
skul add --help(and anyskul <cmd> --help) now returns command-specific help text instead of erroringCliParseResulthelp variant carries an optionalcommandfield so the right subcommand help is returned end-to-endTypo correction
e.g.
skul addd→Unknown command: "addd", did you mean "add"?Colorized output
picocolors(zero deps, 1.4 KB): bold headers, cyan bundle names, green for success actions (Applied/Updated/Removed/Reset), yellow forDRY RUN:prefix, dim for hints andClonedlinesNO_COLORis set, or whenSKUL_NO_TUI=1is active —--jsonpaths return before any color calls and are unaffectedActionable error and empty-state messages
Every dead-end message now includes a next-step hint:
Bundle not found: fooBundle not found: foo+ how to add oneskul listwith empty libraryNo cached bundles found.Add one with: skul add …skul statusunconfiguredConfigured: noRun "skul add <bundle>" to get startedskul removeunknown bundleBundle not found in active set: fooskul checkwith updates availableRun "skul update" to apply available updatesskul updateall local-onlyAll selected bundles are already up to dateNo remote-backed bundles to update (foo is local-only)skul <cmd> requires a Git repositoryRun "git init" to initialize oneNo bundles configured for this repositoryRun "skul add <bundle>" to add oneConflict resolution prompts
Labels rewritten to describe consequences rather than actions:
"Rename incoming file"→"Save with a different name (you choose)""Apply prefix (…)"→"Add a prefix to avoid the conflict (saves as …)""Skip file"→"Skip this file (won't be written)"Test plan
skul add --helpprints add-command help;skul --helpprints global helpNO_COLOR=1skul listwith no bundles shows the add hintskul remove nonexistentwhen bundles exist shows configured bundle namesskul updatewith only local-only bundles shows specific messageskul checkwith updates available appends the update hinthttps://claude.ai/code/session_01MHwWwPGhz5gQo4EWJzoAW7