Interactive stack picker for checkout

[skarim]

Builds on the stack-number work: now that we can list every stack in a repo and reference each by its number, gh stack checkout gets a much better no-argument experience. Previously it showed a plain text prompt of your locally tracked stacks only — it couldn't surface stacks that live only on the remote, gave no sense of a stack's state, and listed fully merged stacks you can no longer add to. This replaces that prompt with an interactive picker that reconciles your local stacks with the ones on GitHub.

What's new

• An inline picker. Running gh stack checkout with no argument opens a picker that renders in place over a few lines and clears itself on exit, rather than taking over the whole screen.
• Local and remote stacks in one list. Local stacks (from .git/gh-stack) are merged with the repo's stacks from the Stacks REST API, matched by id/number, and labeled Local (available locally, even if also tracked on the remote) or Remote (only on GitHub).
• Compact, scannable columns — stack number, first…last branch, base branch, a muted status bar summarizing how many of the stack's PRs are merged / open / not yet pushed, type, and relative created time. Fully merged stacks are omitted, since you can't add to them.
• Filter and search — All / Local / Remote tabs, plus / to type-filter. Search matches the stack number, the base, and any branch in the stack — including mid-stack branches that aren't shown in the column.
• Selecting a stack does the right thing — a locally available stack checks out its top unmerged branch; a remote-only stack is cloned down first (through the existing checkout-by-number flow) and then checked out.
• Graceful fallback — if the Stacks API is unavailable (not enabled for the repo, no auth, or a network error), the picker still opens with a local-only list.

Up to ten rows are shown at once with a scroll position indicator, and the list shrinks to fit shorter terminals.

Changes

Add an interactive stack picker for checkout

• internal/tui/checkoutview/ (new package) — data.go reconciles local and remote stacks into the picker's rows (Local/Remote labeling, status counts, merged-stack filtering, sorting); model.go is the Bubble Tea model (inline rendering, tabs, / search, scrolling, selection, clear-on-exit); styles.go holds the table and status-bar styling.
• cmd/checkout.go — the no-argument path now fetches remote stacks (best-effort), builds the rows, launches the picker, and routes the selection (local checkout vs. remote clone-by-number), falling back to a local-only list when the API is unavailable. Updated the command help text.
• README.md, docs/ CLI reference and overview — document the new picker.

Search by entire branch list

• internal/tui/checkoutview/{data,model}.go — each row now carries every branch name in the stack (not just the shown first/last), and the search haystack includes them all, so a mid-stack branch matches even though it isn't displayed.

Testing

• New unit tests for the reconciliation/row-building, the model (tabs, search including mid-stack matches, navigation, selection, bounded inline height, and clear-on-exit), and the cmd wiring (remote fetch + local-only fallback, and local vs. remote selection routing).
• go test -race ./..., go vet ./..., and gofmt are clean, and each of the two commits builds and passes tests independently.

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

Adds an inline, searchable checkout picker combining local and remote stacks.

Changes:

• Reconciles local and remote stacks, filtering fully merged stacks.
• Supports tabs, search, scrolling, status summaries, and remote cloning.
• Adds picker tests and updates checkout documentation.

Show a summary per file

File	Description
README.md	Documents the picker workflow.
cmd/checkout.go	Integrates picker and selection routing.
cmd/checkout_picker_test.go	Tests checkout picker integration.
docs/src/content/docs/reference/cli.md	Updates CLI reference.
docs/src/content/docs/introduction/overview.md	Updates checkout overview.
internal/tui/checkoutview/data.go	Builds reconciled picker rows.
internal/tui/checkoutview/data_test.go	Tests row reconciliation.
internal/tui/checkoutview/model.go	Implements picker interaction and rendering.
internal/tui/checkoutview/model_test.go	Tests picker behavior.
internal/tui/checkoutview/styles.go	Defines picker styling and status bars.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 7
• Review effort level: Medium

[Lukeghenco]

🥳