feat(prompts): add scroll indicators and interactive listage module

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.

[rafa-thayto]

Summary

• Add custom select/search prompts in lib/listage.ts built on @inquirer/core's createPrompt that show ↑ N more above / ↓ N more below scroll indicators when choices overflow the visible page
• Consolidate the piped-stdin TTY fallback (previously only in lib/prompts.ts for select/confirm, missing for search) and the duplicated filterChoices helper into the shared listage module
• Add interactive environment picker to clerk switch-env when no argument is given in human mode

Why custom prompts?

@inquirer/select v5 and @inquirer/search v4 removed the old helpMode theme option, and usePagination returns a plain string with no metadata about items above/below the viewport. There's no theme hook or callback to inject scroll indicators without reimplementing the render function via createPrompt.

Commands updated

Command	Prompt type	What it picks
clerk link	search	Clerk application
clerk init	search	Framework, package manager
clerk api (interactive)	select	API category, endpoint
clerk deploy	select	Domain type, OAuth flow
clerk switch-env	select (new)	Environment (when no arg given)

Other improvements

• search prompts now have the TTY fallback for piped stdin (previously missing — link and init/bootstrap imported search directly from @inquirer/prompts)
• Removed duplicated filterChoices helper from init/bootstrap.ts (now shared from listage.ts)

Test plan

• Run clerk api with no args — verify scroll indicators appear on the endpoint list when it exceeds page size
• Run clerk link — verify app picker shows scroll indicators with many apps
• Run clerk switch-env with no argument — verify interactive picker appears
• Run clerk switch-env staging — verify direct argument still works
• Pipe stdin (echo | clerk switch-env) — verify fallback to text output
• Verify all CI checks pass (typecheck, lint, tests)

[coderabbitai]

Warning

Rate limit exceeded

@rafa-thayto has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 9 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 49 minutes and 9 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e221dfa-8853-4ca8-8455-86aaf77c330a

📥 Commits

Reviewing files that changed from the base of the PR and between c5743ea and 4f8e2e6.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/preview.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/unlink/index.test.ts
• packages/cli-core/src/commands/unlink/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.test.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/listage-stubs.ts
• packages/cli-core/src/test/lib/stubs.ts

📝 Walkthrough

Walkthrough

A new shared module packages/cli-core/src/lib/listage.ts implements custom interactive prompts (select, search) with case-insensitive filtering, pagination, and stable scroll indicators. Several command modules (deploy, api/interactive, init/bootstrap, init/skills, link, switch-env) now import prompts or helpers from this module instead of @inquirer/prompts. switch-env gains interactive environment picking when invoked without an argument in human mode. Tests and test harnesses are updated to mock listage; package.json adds @inquirer/ansi and @inquirer/figures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding scroll indicators and introducing a new interactive listage module for prompts.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the purpose, affected commands, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f8e2e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wyattjoh]

Code Review — PR #176

Reviewed with Opus + Codex second-opinion validation.

High

H1. TTY fallback does not handle /dev/tty or CONIN$ open failures(codex confirmed)
packages/cli-core/src/lib/listage.ts:42-45 unconditionally calls createReadStream(TTY_PATH) when stdin is not a TTY, without attaching an error listener. In Docker without --tty, detached CI runners, or Windows sessions without CONIN$, the stream emits an async error event that is unhandled. Previously the same flaw existed in lib/prompts.ts but is now extended to search callsites (link, init/bootstrap).

H2. Scroll indicator math ignores rendered-line wrapping(codex confirmed)
scrollBounds() (listage.ts:68-95) counts items, but @inquirer/core's usePagination paginates on rendered lines post-breakLines(). Long clerk api labels or narrow terminals produce wrapped choices, which means the "more above/below" counts and visible-range inference diverge from what is actually shown.

Medium

• M1. Prompt height jumps 1 line at edges (listage.ts:104-107,115-117): only the non-empty indicator row renders at top/bottom.
• M2.Math.max(pageSize - 2, 3) plus indicator rows (listage.ts:294,508): callers passing pageSize: 3 or 4 get 4-5 lines.
• M3. Zero direct tests for lib/listage.ts. Every command mocks it out; scrollBounds, withScrollIndicators, normalizeChoices, isSelectable, the TTY fallback, keypress handlers, and search race-cancellation are all unverified. Add at minimum a lib/listage.test.ts for the pure helpers.
• M4.ValidationError thrown inside useMemo (listage.ts:216-223) is not guaranteed to be caught by @inquirer/core's validation path; prefer validating up-front in the select() wrapper.
• M5.searchactive can be -1 with empty results (listage.ts:417-423,461): the useState<number>() destructure default only applies when the value is strictly undefined, not for the bounds.first = -1 case.
• M6.cursorHide is appended on every select render (listage.ts:340) with no matching cursorShow on the done branch (listage.ts:319-321). Commands that chain prompts (deploy, api/interactive) can render subsequent prompts with a hidden cursor.
• M7. Duplicate select API surface: old lib/prompts.ts:36-46 still exports select, and commands/init/skills.ts:17,106-113 still uses it. Two implementations with different appearance and TTY-fallback paths.
• M8.packages/cli-core/src/commands/switch-env/README.md is not updated despite the new interactive picker behavior (per .claude/rules/commands.md).

Missed on first pass (codex caught)

• All-disabled list deadlock.listage.ts:217-220 checks isNavigable rather than isSelectable; an all-disabled list never throws and produces a prompt with no selectable item and no exit path.
• Stuck loading state on search error.listage.ts:427-453 sets status to "loading" before fetch but the error path never resets it to "idle", leaving the prompt loading indefinitely and blocking arrow-key nav (listage.ts:485-494).

Nits

• isSelectable<T> narrows to { disabled?: false } but runtime accepts any falsy disabled (listage.ts:124-126).
• rl.clearLine(0) on arrow keys clobbers the type-ahead buffer (listage.ts:251-260).
• Type-ahead startsWith lacks Unicode normalization (listage.ts:275-278).
• SelectConfig / SearchConfig types not exported (listage.ts:185-191,378-390).
• • bullet in keysHelpTip may not render in all terminals (listage.ts:201,401).
• switch-env/index.ts:30 reassigns the function parameter.
• @inquirer/ansi and @inquirer/figures added as direct deps though already transitive.

Positives

Clear motivation in the PR body (upstream removed helpMode / usePagination metadata). Abort-controller wiring in the search useEffect correctly cancels stale results. The defaultApplied.current ref is a subtle bug fix that is easy to miss. Deduplication of filterChoices from init/bootstrap.ts into the shared module is a net cleanup. Changeset scoped as minor matches the surface-visible change.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli-core/src/lib/listage.ts`:
- Around line 495-504: The up/down key handler can enter a do…while loop when
searchResults is empty, causing NaN/index errors; update the condition that
currently reads "status !== 'loading' && (isUpKey(key) || isDownKey(key))" (and
the subsequent guard using bounds.first/last) to also require
searchResults.length > 0 (or equivalently bounds.first !== -1) before attempting
to compute next and call isSelectable; ensure functions/vars referenced are
status, isUpKey, isDownKey, bounds, active, searchResults, isSelectable, and
setActive so the handler early-returns when there are no results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a8291374-2d47-4d13-8d6e-816d4354a86b

📥 Commits

Reviewing files that changed from the base of the PR and between a2fd8f2 and c5743ea.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/api/interactive.test.ts
• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/README.md
• packages/cli-core/src/commands/switch-env/index.test.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/lib/listage.test.ts
• packages/cli-core/src/lib/listage.ts
• packages/cli-core/src/lib/prompts.ts
• packages/cli-core/src/test/integration/lib/harness.ts
• packages/cli-core/src/test/lib/stubs.ts

✅ Files skipped from review due to trivial changes (5)

• packages/cli-core/src/commands/switch-env/README.md
• .changeset/listage-improvements.md
• packages/cli-core/package.json
• packages/cli-core/src/commands/link/index.test.ts
• packages/cli-core/src/test/integration/lib/harness.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/cli-core/src/commands/api/interactive.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/switch-env/index.ts
• packages/cli-core/src/commands/link/index.ts
• packages/cli-core/src/commands/switch-env/index.test.ts

[wyattjoh]

Code review

Net positive change: a small custom select/search on top of @inquirer/core that adds scroll indicators, fills in the piped-stdin TTY fallback that search was missing, and ships an interactive env picker for switch-env. Implementation is careful and the scrollBounds test coverage is good. A few things worth tightening before merge.

[Railly]

Arrow navigation lands on disabled items (lib/listage.ts:265). Uses isNavigable instead of isSelectable, upstream @inquirer/select uses isSelectable in the equivalent loop, and the search prompt below (:502) uses it too, so select is the odd one out. Coupled render quirk at :317-318 (cursor ❯ renders on active disabled rows) fixes itself once the loop predicate is corrected.