feat(cli): implement rich UX layer, spinners, and polished command output

[weroperking]

Motivation

• Improve the CLI first-impression and runtime feedback by replacing ad-hoc chalk messages with structured, consistent terminal primitives and spinner-backed progress indicators.
• Make interactive flows (notably bb init and bb login) clearer and safer (one-time key reveals, destructive-op warnings, elapsed timers) so users know what to do and when operations are happening.
• Provide a single place for formatting and global error handling so help output, error hints, and --debug stack traces are consistent across commands.

Description

• Replaced the old logger with a richer API in packages/cli/src/utils/logger.ts introducing sym, section, keyValue, tree, box, badge, step, done, blank, banner, keyValue, and other helpers used throughout the CLI.
• Added a spinner utility packages/cli/src/utils/spinner.ts with createSpinner() and withSpinner() (built on ora) to wrap async tasks and persist success/failure state.
• Updated CLI commands to use the new UX primitives: packages/cli/src/commands/init.ts, login.ts, dev.ts, migrate.ts, generate.ts, iac/sync.ts, and function.ts now show structured headers, file trees, boxes for sensitive values, per-step spinners, timestamped events, and clearer destructive-operation messages.
• Enhanced the global CLI entry packages/cli/src/index.ts to configure Commander help styling, add examples/docs help text, expose a --debug flag, route Commander error output through the logger, and add global uncaughtException/unhandledRejection handlers that emit short hints (with optional stack traces in debug mode).
• Added UX-related dependencies to packages/cli/package.json: ora and cli-table3 (and updated lockfile accordingly) to support spinners and future table output.

Testing

• Ran bun install at repo root and dependency installation completed successfully.
• Ran bun run --cwd packages/cli typecheck and TypeScript typecheck succeeded with no errors.
• Ran bun test --cwd packages/cli and the test suite passed: all CLI tests passed (348 passed, 0 failed).

---

Codex Task

Summary by CodeRabbit

Release Notes

New Features

• Added --debug flag to CLI for verbose error output and troubleshooting

Improvements

• Enhanced terminal output with progress spinners for long-running operations (bundling, deployments, migrations, schema syncing)
• Improved visual formatting and structured information display across all CLI commands
• Better organized output for init, login, dev, and migrate workflows with clearer success messages and step indicators

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e75af098-9ec2-44ed-bcd0-17f2ff423258

📥 Commits

Reviewing files that changed from the base of the PR and between 86bb1d7 and d7732f6.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (11)

• packages/cli/package.json
• packages/cli/src/commands/dev.ts
• packages/cli/src/commands/function.ts
• packages/cli/src/commands/generate.ts
• packages/cli/src/commands/iac/sync.ts
• packages/cli/src/commands/init.ts
• packages/cli/src/commands/login.ts
• packages/cli/src/commands/migrate.ts
• packages/cli/src/index.ts
• packages/cli/src/utils/logger.ts
• packages/cli/src/utils/spinner.ts

---

Walkthrough

Introduces new npm dependencies (cli-table3, ora) and refactors CLI commands and utilities to implement structured terminal output with spinner-driven progress, colored formatting, and new logging primitives for improved user-facing output.

Changes

Cohort / File(s)	Summary
Dependencies packages/cli/package.json	Added runtime dependencies: cli-table3@^0.6.5 and ora@^8.0.0.
Terminal UI Infrastructure packages/cli/src/utils/spinner.ts, packages/cli/src/utils/logger.ts, packages/cli/src/index.ts	New spinner module exports createSpinner and withSpinner for progress indication. Logger refactored from string-returning formatters to direct-output functions; added sym symbol object, dim, step, section, keyValue, tree, blank, banner, box, badge, done, and optional hint parameter on error(). Main CLI adds --debug flag, customizes Commander output/help rendering with chalk colors and branding, installs uncaught exception and rejection handlers with error messaging and conditional stack traces.
Dev Command packages/cli/src/commands/dev.ts	Replaced cyan banner with structured header using blank, keyValue, sym. Schema change events now log with timestamp and "→ regenerating context" marker. Context regeneration measures elapsed time and emits timestamped success message; error handling changed to explicit .then().catch() chain.
Generate Command packages/cli/src/commands/generate.ts	Schema scanning, route file writing, and router index updates wrapped in withSpinner. Output replaced plain logger.success with structured "Generated endpoints" section showing color-coded HTTP methods, endpoints, and descriptions; added section header and tree file outline.
Function Command packages/cli/src/commands/function.ts	Bundling step wrapped in withSpinner with success text. Deployment UI changed to spinner with dynamic text update. Final output replaced raw console.log lines with logger.box summary including function, target, and deployment URL.
Migrate Command packages/cli/src/commands/migrate.ts	Migration generation and Drizzle push wrapped in withSpinner. Completion logging replaced with logger.done(startTime, ...) for timing. Destructive changes output enhanced with yellow header, explicit blank lines, and red bullet markers.
Init Command packages/cli/src/commands/init.ts	Added formatted header via chalk. Success output replaced with structured logger.section and logger.tree, listing created files and displaying "Next steps" as numbered list with colored styling and environment variable reminders.
Login Command packages/cli/src/commands/login.ts	Output refactored to use blank, section, keyValue for authorization flow. Token polling now uses spinner with elapsed-time tracking and explicit stop on error. Success persists spinner with symbol and renders "Logged in" box before legacy success line. Timeout now stops spinner before error exit.
IaC Sync Command packages/cli/src/commands/iac/sync.ts	Captures startTime and reports completion via done(). Non-silent output adds section header and groups diff.changes into added, modified, removed buckets with color-coded sym.bullet markers. Drizzle schema generation conditional: silent mode generates directly; non-silent wraps in withSpinner.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• PR #42 — Modifies CLI surface with spinner/logger utilities and multiple IaC/command handlers touching the same command functions and utility modules.
• PR #27 — Overlaps on packages/cli/src/commands/migrate.ts changes affecting migration generation and completion flow.
• PR #25 — Overlaps on logger/spinner utilities and login command refactoring with shared terminal UI patterns.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/implement-cli-ux-improvements-and-error-handling

---

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.}