api: add high-level implicit-ref Lua entrypoints #393

New issue

Closed

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

barrettruth commented

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

Part of #389.
Depends on #390.
Suggested order: 4.

Problem

The documented Lua surface leans on low-level forge.ops helpers that mostly expect already-resolved IDs and scopes. That diverges from the canonical Ex model and forces integrations to reconstruct internal targeting details for common workflows.

Proposed solution

Add a high-level Lua surface that matches the new Ex semantics and reuses the shared resolver layer.

Suggested canonical entrypoints:

forge.pr(opts?)
forge.review(opts?)
forge.pr_ci(opts?)
forge.ci(opts?)
forge.current_pr(opts?)

These should support the common implicit case with no arguments and explicit disambiguation through address-style options where needed.

Scope

add the new top-level entrypoints in require(forge)
route them through the shared resolver / command semantics
support explicit current-ref targeting via high-level opts where appropriate
add Lua-facing specs for the new behavior

Acceptance criteria

common branch-relative workflows no longer require callers to manually construct { num, scope } tables
top-level Lua entrypoints behave consistently with the matching Ex commands
forge.ci() remains current-branch CI, while forge.pr_ci() means PR checks

Out of scope

removing existing low-level helpers
final documentation and migration cleanup

Part of #389. Depends on #390. Suggested order: 4. ## Problem The documented Lua surface leans on low-level `forge.ops` helpers that mostly expect already-resolved IDs and scopes. That diverges from the canonical Ex model and forces integrations to reconstruct internal targeting details for common workflows. ## Proposed solution Add a high-level Lua surface that matches the new Ex semantics and reuses the shared resolver layer. Suggested canonical entrypoints: - `forge.pr(opts?)` - `forge.review(opts?)` - `forge.pr_ci(opts?)` - `forge.ci(opts?)` - `forge.current_pr(opts?)` These should support the common implicit case with no arguments and explicit disambiguation through address-style options where needed. ## Scope - add the new top-level entrypoints in `require(forge)` - route them through the shared resolver / command semantics - support explicit current-ref targeting via high-level opts where appropriate - add Lua-facing specs for the new behavior ## Acceptance criteria - common branch-relative workflows no longer require callers to manually construct `{ num, scope }` tables - top-level Lua entrypoints behave consistently with the matching Ex commands - `forge.ci()` remains current-branch CI, while `forge.pr_ci()` means PR checks ## Out of scope - removing existing low-level helpers - final documentation and migration cleanup