Tracker: implicit current-ref command and API surface #389

New issue

Closed

opened 2026-04-25 16:20:50 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-25 16:20:50 +00:00

Problem

Forge currently exposes three overlapping models for the same workflows:

Ex commands with family verb plus textual target modifiers like repo= and head=
picker routes like prs.open and ci.current_branch
Lua APIs that mostly operate on already-resolved { num, scope } or split head_branch / head_scope inputs

The common "current PR for the current branch" flow is not a first-class public concept, even though the backend primitive already exists. That leaves important workflows discoverable only through overloaded commands such as :Forge pr create.

Proposed solution

Adopt an implicit current-ref model for the common case and keep explicit targeting for ambiguity:

:Forge pr -> current branch PR
:Forge review -> current branch PR through the configured adapter
:Forge pr ci -> current branch PR checks
:Forge ci -> current-branch CI history, not PR checks

Under the hood, add a shared resolver layer that maps current branch context (or explicit repo= / head= input) onto a unique PR when possible. Then align the high-level Lua API with the same semantics.

Resolver policy

Resolve from current push context first
Fall back to configured collaboration repo only when needed
Match by { head_scope, head_branch }, not branch name alone
If there is no open PR, opt out cleanly
If there is exactly one open PR, use it
If there are multiple matches, stop and require explicit repo= or head=

Ordered breakdown

#390 resolver: add current-PR resolution from head context
#391 cmd: add implicit current-PR Ex commands, completion, and specs
#392 cmd: make :Forge pr create strictly create-only
#393 api: add high-level implicit-ref Lua entrypoints
#394 docs: rewrite vimdoc and migration notes for implicit refs
#395 cleanup: evict old low-level public Lua APIs after migration

Alternatives considered

Keep the current mixed surface and only improve messages, or make :Forge ci silently prefer PR checks. Both leave the public model inconsistent across forges.

## Problem Forge currently exposes three overlapping models for the same workflows: - Ex commands with `family verb` plus textual target modifiers like `repo=` and `head=` - picker routes like `prs.open` and `ci.current_branch` - Lua APIs that mostly operate on already-resolved `{ num, scope }` or split `head_branch` / `head_scope` inputs The common "current PR for the current branch" flow is not a first-class public concept, even though the backend primitive already exists. That leaves important workflows discoverable only through overloaded commands such as `:Forge pr create`. ## Proposed solution Adopt an implicit current-ref model for the common case and keep explicit targeting for ambiguity: - `:Forge pr` -> current branch PR - `:Forge review` -> current branch PR through the configured adapter - `:Forge pr ci` -> current branch PR checks - `:Forge ci` -> current-branch CI history, not PR checks Under the hood, add a shared resolver layer that maps current branch context (or explicit `repo=` / `head=` input) onto a unique PR when possible. Then align the high-level Lua API with the same semantics. ## Resolver policy - Resolve from current push context first - Fall back to configured collaboration repo only when needed - Match by `{ head_scope, head_branch }`, not branch name alone - If there is no open PR, opt out cleanly - If there is exactly one open PR, use it - If there are multiple matches, stop and require explicit `repo=` or `head=` ## Ordered breakdown 1. #390 resolver: add current-PR resolution from head context 2. #391 cmd: add implicit current-PR Ex commands, completion, and specs 3. #392 cmd: make `:Forge pr create` strictly create-only 4. #393 api: add high-level implicit-ref Lua entrypoints 5. #394 docs: rewrite vimdoc and migration notes for implicit refs 6. #395 cleanup: evict old low-level public Lua APIs after migration ## Alternatives considered Keep the current mixed surface and only improve messages, or make `:Forge ci` silently prefer PR checks. Both leave the public model inconsistent across forges.