fix(cli): runner-aware help banners + wizard reference

[coderdan]

Closes #385.

Follow-up to #377 addressing Lindsay's feedback that the --help banners and the wizard suggestion in db install's "Next steps" panel still hard-coded npx @cipherstash/cli regardless of how the user invoked the CLI.

#379 already shipped runnerCommand(pm, ref) + detectPackageManager(). This applies them to the remaining places.

Before / after

$ bunx @cipherstash/cli --help

# Before
Usage: npx @cipherstash/cli <command> [options]
Examples:
  npx @cipherstash/cli init
  npx @cipherstash/cli db install
  ...

# After
Usage: bunx @cipherstash/cli <command> [options]
Examples:
  bunx @cipherstash/cli init
  bunx @cipherstash/cli db install
  ...

Same for pnpm dlx, yarn dlx, default npx.

Touches

• bin/stash.ts — HELP interpolates a STASH constant (runnerCommand(PM, '@cipherstash/cli')) for the usage line, six examples, and the requireStack hint shown when @cipherstash/stack isn't installed.
• commands/auth/index.ts — same pattern for the auth HELP (usage line + two examples).
• commands/db/install.ts — the wizard line in printNextSteps uses runnerCommand(pm, '@cipherstash/wizard').

Messages

messages.cli.usagePrefix and messages.auth.usagePrefix become stable leaders ('Usage: ') — the runner+package portion is appended at render time. The smoke E2E tests already use toContain against these constants, so they stay runner-agnostic without test changes.

Out of scope

messages.db.migrateNotImplemented keeps its hard-coded npx form. db migrate is a not-yet-implemented stub; the inconsistency only surfaces when someone runs a command that doesn't exist yet. Not worth plumbing.

Manual test plan

I ran each of the below locally; would appreciate reviewers running them too.

git checkout dan/runner-aware-help-banners
pnpm install
pnpm --filter @cipherstash/cli build
STASH=$PWD/packages/cli/dist/bin/stash.js

Detection prefers npm_config_user_agent over lockfile; overriding it directly is the easiest way to test each runner without installing them.

1. Top-level --help — Usage line and the six Examples should all use the runner:

```sh
node $STASH --help # → npx (default)
npm_config_user_agent='bun/1.x' node $STASH --help # → bunx
npm_config_user_agent='pnpm/9.x' node $STASH --help # → pnpm dlx
npm_config_user_agent='yarn/4.x' node $STASH --help # → yarn dlx
```

2. auth --help (or just auth with no subcommand):

```sh
npm_config_user_agent='bun/1.x' node $STASH auth

Expected: "Usage: bunx @cipherstash/cli auth [options]"

Examples: "bunx @cipherstash/cli auth login" / "...auth login --supabase"

```

3. db install "Next steps" panel — the wizard line should match the runner:

```sh
mkdir /tmp/runner-test && cd /tmp/runner-test
DATABASE_URL=postgresql://test/x npm_config_user_agent='bun/1.x' \
node $STASH db install --dry-run

When the panel prints, the wizard line should read:

bunx @cipherstash/wizard

(You'll also see "bunx @cipherstash/cli db install" as the intro — covered by #377.)

```

4. requireStack hint — surfaces when running db push/validate/schema build without @cipherstash/stack installed:

```sh
cd /tmp/runner-test
DATABASE_URL=postgresql://test/x npm_config_user_agent='pnpm/9.x' \
node $STASH db push

Expected error:

@cipherstash/stack is required for this command.

Install it with: pnpm add @cipherstash/stack

Or run: pnpm dlx @cipherstash/cli init

```

5. Lockfile fallback — without npm_config_user_agent, detection falls back to lockfile:

```sh
cd /tmp/runner-test
touch bun.lock
node $STASH --help # without npm_config_user_agent override

Expected: bunx-flavoured output

rm bun.lock && touch pnpm-lock.yaml
node $STASH --help

Expected: pnpm dlx

rm pnpm-lock.yaml
```

Automated coverage

Surface	Coverage
runnerCommand / detectPackageManager themselves	Unit-tested in src/commands/init/__tests__/utils.test.ts (from #379)
Top-level --help Usage line + Examples	New E2E in tests/e2e/runner-aware-help.e2e.test.ts — 4 cases (npx / bunx / pnpm dlx / yarn dlx) asserting the right runner appears
auth --help Usage line + Examples	Same file, 4 more cases
db install "Next steps" panel (wizard line)	Not covered — would need a successful install (real DB). Manual only.
requireStack hint	Not covered — workspace has @cipherstash/stack installed so the path doesn't fire in CI. Manual only.
messages.cli.usagePrefix no longer hardcoded with npx	Smoke E2E (existing) already passes regardless of runner thanks to the leader-only assertion

The two gaps (Next-steps panel and requireStack hint) are awkward to E2E without standing up a real DB or surgically removing @cipherstash/stack from the test environment. If a future PR adds either of those harnesses, both would be cheap to cover then.

Test plan

• pnpm --filter @cipherstash/cli build clean
• pnpm --filter @cipherstash/cli test — unit tests pass
• pnpm --filter @cipherstash/cli test:e2e — 18 E2E tests pass (was 10; +8 from new runner-aware-help.e2e.test.ts)
• biome check clean on changed files
• Manual: ran node dist/bin/stash.js --help with npm_config_user_agent cleared / set to pnpm/9 / set to bun/1 and confirmed the rendered Usage line + Examples match the runner.
• Rebased onto post-feat(cli): layered DATABASE_URL resolution for db / schema commands #377 main

[changeset-bot]

🦋 Changeset detected

Latest commit: 03d845e

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

This PR includes changesets to release 2 packages

Name	Type
@cipherstash/cli	Patch
@cipherstash/e2e	Patch

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

[coderabbitai]

Warning

Rate limit exceeded

@coderdan has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 30 minutes and 10 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7e98da25-684d-4fd5-9d84-b9548595021d

📥 Commits

Reviewing files that changed from the base of the PR and between 2336062 and 03d845e.

📒 Files selected for processing (6)

• .changeset/cli-runner-aware-help-banners.md
• packages/cli/src/bin/stash.ts
• packages/cli/src/commands/auth/index.ts
• packages/cli/src/commands/db/install.ts
• packages/cli/src/messages.ts
• packages/cli/tests/e2e/runner-aware-help.e2e.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dan/runner-aware-help-banners

---

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

_{Review rate limit: 0/1 reviews remaining, refill in 30 minutes and 10 seconds.}

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