feat(cli): restructure command surface for clarity and discoverability by vladtara · Pull Request #19 · glapsfun/gskill

vladtara · 2026-07-05T20:00:08Z

Summary

Implements spec 010 (CLI command ergonomics), phase 1 of the command-surface redesign: grouping, renames, discoverable help, typo suggestions, actionable errors — with full backward compatibility.

Taxonomy: 24 flat commands → 19 top-level entries in 4 help sections (CORE / INSPECT / PROJECT / MORE); sync/repair/lock/verify/check/diff fold under a new project group; find→search, tui→dashboard.
Compatibility: every old invocation still works as a silent hidden alias, driven by one declarative alias table and proven byte-identical by table-driven tests. No deprecation nags. Exit codes unchanged.
Help: grouped root help via kong groups; Usage + copy-pasteable Examples: block on every command; all pages locked by golden files (with a completeness guard so future commands can't ship without one).
Navigation: bare group invocations (gskill project) print group help and exit 0 — except under --json, which stays a strict usage error with clean stdout.
Did you mean?: deterministic, alias-aware suggestions for root-level typos (gskill sinc → project sync), scoped via kong's ParseError context so subcommand/trailing-arg errors keep kong's own message.
Errors: errs.Error gains Hint/WithHint/HintOf; the CLI renders a trailing → next step line on stderr across ~20 audited error sites, with a reviewed no-next-step exception list.
Safety: confirmation prompts for remove and project sync --prune (TTY-gated on both stdin and stdout, never blocks CI, --yes honored); install --global --project now rejected via xor.
Derived surfaces: shell completion and docs/reference/commands.md generated from the live kong grammar; prose docs swept to canonical command forms.

Test plan

33 golden help pages + structural section/count assertions
Alias equivalence suite (byte-identical stdout/stderr/exit code, fresh project per side)
Suggestion, hint-audit, confirmation, and completion coverage tests (all red-first per constitution IV)
./scripts/verify.sh green: fmt, vet, golangci-lint, race tests + coverage floor, govulncheck, gitleaks

Fold the six maintenance commands (sync, repair, lock, verify, check, diff) under a new `project` group and rename find->search and tui->dashboard, while every pre-existing flat invocation keeps working as a silent hidden alias driven by a single declarative alias table. - grouped root help (CORE / INSPECT / PROJECT / MORE) via kong groups, with a Usage line and copy-pasteable Examples: block on every command, all locked by golden-file tests - bare group invocations (e.g. `gskill project`) print group help and exit 0, except under --json where strict usage errors are preserved - deterministic alias-aware "did you mean?" suggestions for root-level typos, scoped via kong's ParseError context so trailing arguments and subcommand errors keep kong's own message - actionable error hints: errs.Error gains Hint/WithHint/HintOf and the CLI renders a trailing "-> next step" line on stderr; hints attached across app-layer error sites with a reviewed exception list - confirmation prompts (stdin+stdout TTY gated, --yes/non-interactive safe) for remove and project sync --prune - shell completion and reference docs derived from the live kong grammar; prose docs swept to canonical command forms

Copilot

Pull request overview

This PR implements phase 1 of the “spec 010” CLI ergonomics redesign by reorganizing the gskill command surface into grouped help sections, introducing canonical command renames (find→search, tui→dashboard), moving maintenance operations under a project group, and adding alias-aware UX improvements (help examples, typo suggestions, actionable hints) while preserving backward-compatible aliases.

Changes:

Restructures the CLI grammar into CORE / INSPECT / PROJECT / MORE sections, adds canonical renames, and keeps old commands as silent aliases (including project regrouping).
Introduces hint-carrying errors (errs.WithHint, errs.HintOf) and renders “→ next step” hints consistently on CLI errors.
Locks help output and docs generation via extensive golden files, completion derivation, and coverage tests for aliases, suggestions, and confirmation prompts.

Reviewed changes

Copilot reviewed 89 out of 89 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates README examples and command reference to new canonical command taxonomy.
internal/errs/hint_test.go	Adds tests ensuring hints preserve message, exit code mapping, and unwrap semantics.
internal/errs/errs.go	Adds Hint support to typed errors and utilities to attach/find hints.
internal/docs/reference.go	Updates command reference generation to annotate kong aliases and skip hidden nodes.
internal/cli/verify.go	Adds Help examples and attaches repair hint on integrity failures.
internal/cli/update.go	Adds Help examples for `update`.
internal/cli/unlink.go	Adds Help examples for `unlink`.
internal/cli/tui.go	Documents canonical `dashboard` name and adds Help examples.
internal/cli/testdata/help/version.golden	Adds golden help page for `version`.
internal/cli/testdata/help/update.golden	Adds golden help page for `update`.
internal/cli/testdata/help/unlink.golden	Adds golden help page for `unlink`.
internal/cli/testdata/help/status.golden	Adds golden help page for `status`.
internal/cli/testdata/help/source-list.golden	Adds golden help page for `source list`.
internal/cli/testdata/help/source-inspect.golden	Adds golden help page for `source inspect`.
internal/cli/testdata/help/source-check.golden	Adds golden help page for `source check`.
internal/cli/testdata/help/search.golden	Adds golden help page for `search` (alias: `find`).
internal/cli/testdata/help/root.golden	Adds golden help page for grouped root help.
internal/cli/testdata/help/remove.golden	Adds golden help page for `remove`.
internal/cli/testdata/help/project.golden	Adds golden help page for `project` group.
internal/cli/testdata/help/project-verify.golden	Adds golden help page for `project verify`.
internal/cli/testdata/help/project-sync.golden	Adds golden help page for `project sync`.
internal/cli/testdata/help/project-repair.golden	Adds golden help page for `project repair`.
internal/cli/testdata/help/project-lock.golden	Adds golden help page for `project lock`.
internal/cli/testdata/help/project-diff.golden	Adds golden help page for `project diff`.
internal/cli/testdata/help/project-check.golden	Adds golden help page for `project check`.
internal/cli/testdata/help/outdated.golden	Adds golden help page for `outdated`.
internal/cli/testdata/help/list.golden	Adds golden help page for `list`.
internal/cli/testdata/help/install.golden	Adds golden help page for `install` (including scope flags).
internal/cli/testdata/help/init.golden	Adds golden help page for `init`.
internal/cli/testdata/help/info.golden	Adds golden help page for `info`.
internal/cli/testdata/help/doctor.golden	Adds golden help page for `doctor`.
internal/cli/testdata/help/dashboard.golden	Adds golden help page for `dashboard` (alias: `tui`).
internal/cli/testdata/help/config-path.golden	Adds golden help page for `config path`.
internal/cli/testdata/help/config-list.golden	Adds golden help page for `config list`.
internal/cli/testdata/help/config-get.golden	Adds golden help page for `config get`.
internal/cli/testdata/help/completion.golden	Adds golden help page for `completion`.
internal/cli/testdata/help/cache-stats.golden	Adds golden help page for `cache stats`.
internal/cli/testdata/help/cache-path.golden	Adds golden help page for `cache path`.
internal/cli/testdata/help/cache-list.golden	Adds golden help page for `cache list`.
internal/cli/testdata/help/cache-clean.golden	Adds golden help page for `cache clean`.
internal/cli/testdata/help/add.golden	Adds golden help page for `add`.
internal/cli/sync.go	Adds Help examples and confirmation for `project sync --prune`.
internal/cli/suggest_test.go	Adds tests for alias-aware, deterministic typo suggestions and JSON strictness.
internal/cli/status.go	Adds Help examples for `status`.
internal/cli/source.go	Adds Help examples for `source` subcommands.
internal/cli/root.go	Implements grouped command grammar, missing-subcommand help courtesy, and alias-aware suggestions + hint rendering.
internal/cli/root_test.go	Updates root help test expectations to new command surface.
internal/cli/repair.go	Adds Help examples and updates canonical invocation to `project repair`.
internal/cli/remove.go	Adds Help examples and confirmation prompt for `remove`.
internal/cli/project.go	Introduces `project` command group and reuses existing maintenance command structs.
internal/cli/output.go	Adds confirmation prompting infrastructure with TTY gating and stdin support.
internal/cli/outdated.go	Adds Help examples and attaches `update` hint on “update available” exit.
internal/cli/lock.go	Adds Help examples and updates canonical invocation to `project lock`.
internal/cli/list.go	Adds Help examples for `list`.
internal/cli/install.go	Adds `--project` scope flag, adds Help examples, and tightens scope xor.
internal/cli/init.go	Adds Help examples for `init`.
internal/cli/info.go	Adds Help examples for `info`.
internal/cli/hint_test.go	Adds tests ensuring hinted errors render arrow line and audits representative hint sites.
internal/cli/help.go	Adds shared Examples block generator for kong HelpProvider.
internal/cli/help_test.go	Adds unit test for Examples block formatting.
internal/cli/help_golden_test.go	Adds golden locking and completeness guard for help pages + grouped-section assertions.
internal/cli/find.go	Renames `find` to canonical `search` with Help examples and alias note.
internal/cli/doctor.go	Adds Help examples for `doctor`.
internal/cli/docs.go	Shares CLI grammar options between runtime and docs model.
internal/cli/diff.go	Adds Help examples and updates canonical invocation to `project diff`.
internal/cli/confirm_test.go	Adds tests for confirmation prompting behavior and non-interactive safety.
internal/cli/config.go	Adds Help examples and wraps unknown-key error with a hint.
internal/cli/completion.go	Derives completion words from live grammar + alias table and adds Help examples.
internal/cli/completion_test.go	Adds completion coverage test for canonical commands and aliases.
internal/cli/check.go	Adds Help examples and attaches sync hint on drift failures.
internal/cli/cache.go	Adds Help examples for cache subcommands.
internal/cli/aliases.go	Defines the declarative alias table as the source of truth for compatibility.
internal/cli/aliases_test.go	Adds tests ensuring aliases parse, remain silent, and behave byte-identically.
internal/cli/add.go	Adds Help examples and removes old `modeFlag` helper usage.
internal/app/unlink.go	Centralizes missing-manifest error and adds actionable hints to unlink error sites.
internal/app/sync.go	Uses shared missing-manifest error with hint.
internal/app/project.go	Adds shared `errNoManifest()` hinted error constructor.
internal/app/lifecycle.go	Uses shared missing-manifest error and adds hint for “skill not declared” update path.
internal/app/install.go	Uses shared missing-manifest error and adds hints for agent targeting failures.
internal/app/frozen.go	Uses shared missing-manifest error and adds hint for unavailable locked agent.
docs/reference/commands.md	Updates generated command reference to new grouping and alias annotations.
docs/how-to/verify-integrity.md	Updates how-to to canonical `project verify` and documents alias.
docs/how-to/use-the-tui.md	Updates how-to to canonical `dashboard` and documents alias.
docs/how-to/update-and-lock.md	Updates lock how-to to canonical `project lock`.
docs/how-to/sync-and-repair.md	Updates how-to to canonical `project sync/repair` and documents aliases.
docs/how-to/script-with-json.md	Updates JSON scripting examples to canonical `project check/verify`.
docs/how-to/inspect-list-info-diff.md	Updates diff examples to canonical `project diff`.
docs/how-to/gate-ci-on-drift.md	Updates CI gating examples to canonical `project check`.
docs/explanation/integrity-and-trust.md	Updates explanation to canonical `project verify`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+gskill project diff              # all skills
+gskill project diff <name>       # one skill


+	if !o.Confirm("Remove foo?", true) {
+		t.Error("Confirm with assumeYes = false, want true")
+	}


Copilot AI review requested due to automatic review settings July 5, 2026 20:00

vladtara merged commit 4b76e08 into main Jul 5, 2026
8 checks passed

Copilot started reviewing on behalf of vladtara July 5, 2026 20:00 View session

Copilot AI reviewed Jul 5, 2026

View reviewed changes

vladtara deleted the 010-cli-command-ergonomics branch July 8, 2026 14:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(cli): restructure command surface for clarity and discoverability#19

feat(cli): restructure command surface for clarity and discoverability#19
vladtara merged 1 commit into
mainfrom
010-cli-command-ergonomics

vladtara commented Jul 5, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		gskill project diff # all skills
		gskill project diff <name> # one skill

Uh oh!

Conversation

vladtara commented Jul 5, 2026

Summary

Test plan

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants