feat: add contextual completion for the new :Forge command language #146

New issue

Closed

opened 2026-04-11 19:02:56 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-11 19:02:56 +00:00

Prerequisites

I have searched existing issues.

Problem

A structured :Forge command language will only feel good if it is discoverable from the command line.

Without contextual completion, users will have to memorize:

family names
verbs
valid modifiers per subcommand
repo aliases/remotes
revision syntax
target syntax

That makes the new CLI harder to learn than the picker, even if it is more precise.

Proposed solution

Add contextual command-line completion for the canonical :Forge interface proposed in #142.

Completion stages

1. Family completion

After :Forge complete:

root
pr
issue
ci
release
browse
unchanged local families if still present

2. Verb completion

Examples:

after :Forge pr -> list, review, checkout, worktree, browse, ci, manage, close, reopen, create, edit, and any newly added parity verbs
after :Forge issue -> list, browse, close, reopen, create

3. Modifier-name completion

Offer only modifiers valid for the resolved family/verb.

Examples:

:Forge pr list -> state=, repo=
:Forge pr create -> head=, base=, draft, fill, web
:Forge ci list -> repo=, rev=, target=, all

4. Modifier-value completion

repo= -> aliases, remotes, recent explicit repos
rev= -> branches, tags, recent SHAs
target= / head= / base= -> repo aliases first, then revisions after @

Initial scope

V1 does not need full remote path completion after :. That can land later.

Acceptance criteria

completion is driven by normalized command shape, not hard-coded token positions
only valid modifiers are suggested for each subcommand
repo= completion includes aliases/remotes
rev= completion includes branches/tags/basic SHA support
target=/head=/base= completion works for repo + revision forms
docs include completion expectations for the new interface

Alternatives considered

Delay completion until after the parser refactor lands. This reduces short-term scope, but it makes the new interface much harder to learn and evaluate.
Offer generic file-style completion for everything. That is simple but much less useful than role-aware completion.

## Prerequisites - [x] I have searched existing issues. ## Problem A structured `:Forge` command language will only feel good if it is discoverable from the command line. Without contextual completion, users will have to memorize: - family names - verbs - valid modifiers per subcommand - repo aliases/remotes - revision syntax - target syntax That makes the new CLI harder to learn than the picker, even if it is more precise. ## Proposed solution Add contextual command-line completion for the canonical `:Forge` interface proposed in #142. ### Completion stages #### 1. Family completion After `:Forge ` complete: - `root` - `pr` - `issue` - `ci` - `release` - `browse` - unchanged local families if still present #### 2. Verb completion Examples: - after `:Forge pr ` -> `list`, `review`, `checkout`, `worktree`, `browse`, `ci`, `manage`, `close`, `reopen`, `create`, `edit`, and any newly added parity verbs - after `:Forge issue ` -> `list`, `browse`, `close`, `reopen`, `create` #### 3. Modifier-name completion Offer only modifiers valid for the resolved family/verb. Examples: - `:Forge pr list ` -> `state=`, `repo=` - `:Forge pr create ` -> `head=`, `base=`, `draft`, `fill`, `web` - `:Forge ci list ` -> `repo=`, `rev=`, `target=`, `all` #### 4. Modifier-value completion - `repo=` -> aliases, remotes, recent explicit repos - `rev=` -> branches, tags, recent SHAs - `target=` / `head=` / `base=` -> repo aliases first, then revisions after `@` ### Initial scope V1 does not need full remote path completion after `:`. That can land later. ### Acceptance criteria - [ ] completion is driven by normalized command shape, not hard-coded token positions - [ ] only valid modifiers are suggested for each subcommand - [ ] `repo=` completion includes aliases/remotes - [ ] `rev=` completion includes branches/tags/basic SHA support - [ ] `target=`/`head=`/`base=` completion works for repo + revision forms - [ ] docs include completion expectations for the new interface ## Alternatives considered - Delay completion until after the parser refactor lands. This reduces short-term scope, but it makes the new interface much harder to learn and evaluate. - Offer generic file-style completion for everything. That is simple but much less useful than role-aware completion.