feat(completion): improve @N<TAB> UX with grouped section menu

[p0fi]

Summary

Fixes #59 — typing matter @1<TAB> previously showed nothing useful (or only sibling nodes sharing the @1 prefix). Users had to already know to type / for endpoints or for device commands.

This PR wires up a four-section completion menu when the typed token is an exact numeric node ID:

• Devices — sibling nodes that prefix-match (@1, @11, …)
• Endpoints — node's endpoints (@1/0, @1/1, …)
• Device Commands — target-aware commands (tree, rename, decommission, …)
• Cluster Commands — cluster shorthands (OnOff, LevelControl, …)
• Tools — code, help, …

How it works

Go side (cli/completion/completer.go)

• New TopLevelCommand struct + ExpandSeparator (+) constant.
• TargetCompletionFunc gains a topLevelCommands func() parameter. When the typed token is a bare numeric @N that exactly matches a commissioned node (stage-1b), it emits:
  • @N/EP endpoint tokens (appear under "Endpoints" in zsh)
  • @N+<cmd> expansion tokens for each target-aware root command
• RootCompletionFunc forwards the parameter through.

Helper (cli/cluster.go)

• topLevelCommandsForCompletion() snapshots the visible root cobra commands and tags each as device/cluster/tool. Non-target-aware commands (commission, discover, fabric, use, …) are excluded so the menu stays relevant.

Bug fix (cli/root.go)

• Execute() was stripping @1 from os.Args for __complete invocations, causing cobra to receive an empty argument list. Fixed with an isCompletionInvocation() guard.

Zsh script (cli/completion.go)

• Splits legacy target_cmds into device_targets (@n) and endpoint_targets (@N/EP).
• Parses @N+<cmd> tokens: looks up <cmd> in _matter_group_map, buckets into exp_device/cluster/tool arrays.
• Emits expansion groups with compadd -U -p "@N " so the candidate displays as the bare command name but inserts as @N <cmd> on the command line.

Test plan

• TestTargetCompletionFunc_Stage1b_EndpointsInExactMatch — exact @n emits endpoint tokens
• TestTargetCompletionFunc_Stage1b_CommandsInExactMatch — expansion tokens emitted only for TargetAware commands
• TestTargetCompletionFunc_Stage1b_NamedNoExpansion — alias prefix (@kitchen-light) does NOT trigger expansion
• TestTargetCompletionFunc_Stage1b_NonExistentNodeNoExpansion — @99 (no match) does NOT trigger expansion
• All existing completer tests still pass (mise run test)
• mise run lint passes clean

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves the CLI’s @N<TAB> autocompletion experience by enriching exact numeric node matches with endpoint candidates and grouped “next action” suggestions (device/cluster/tool commands), primarily for the custom zsh completion script.

Changes:

• Extend Go completion logic to emit endpoint candidates (e.g. @N/0, @N/1) and encoded expansion tokens for exact @N matches.
• Add a root-command snapshot helper to provide target-aware top-level commands for completion expansion.
• Update the zsh completion script to split targets into “Devices” vs “Endpoints” sections and to interpret encoded expansion tokens into grouped menus; adjust Execute() behavior for cobra completion invocations.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cli/root.go	Wires root completion with the new top-level command snapshot; adds a guard around ExtractTargetFromArgs for cobra completion invocations.
cli/completion/completer.go	Adds stage-1b exact-match enrichment (endpoints + encoded @N+<cmd> tokens) and updates completion function signatures.
cli/cluster.go	Implements topLevelCommandsForCompletion() to snapshot visible root commands and tag target-awareness.
cli/completion.go	Updates the generated zsh completion script to add “Devices/Endpoints” sections and parse @N+<cmd> tokens into grouped expansions.
cli/completion/completer_test.go	Adds tests covering stage-1b endpoint enrichment and expansion-token emission rules.
cli/rename.go	Updates call site for the new TargetCompletionFunc(nil) signature.
cli/decommission.go	Updates call site for the new TargetCompletionFunc(nil) signature.
cli/fabric.go	Updates call site for the new TargetCompletionFunc(nil) signature.

---

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