> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/prd-shared/tui-package.md).

# TUI Package

## Purpose

Shared terminal UI primitives for all Gotts CLI consumers. Extracts and enhances the devenv CLI code (\~400 lines) into a reusable package used by:

* **@gotts.ai/devenv** — Deployment progress, ready banners
* **@gotts.ai/create** — Install wizard (interactive prompts, step-by-step tasks)
* **@gotts.ai/portal** — Local portal CLI startup
* **@gotts.ai/safe** — MCP server startup output

## Design Principles

1. **Lightweight deps** — Only `picocolors` (3KB) and `@clack/prompts`. No chalk, boxen, ora, listr2.
2. **TTY-aware** — All output gracefully degrades for non-TTY (CI, piped) environments.
3. **CI-friendly** — `isCI()` detection for all major providers. JSON output mode in reporters.
4. **Branded output** — Consistent Gotts look via `colors.brand()`, `createBanner()`, `createReadyBox()`.
5. **Zero build** — Internal package with direct TS source exports (no tsup/build step).

## Module Catalog

| Module        | Purpose               | Key Exports                                                                                     |
| ------------- | --------------------- | ----------------------------------------------------------------------------------------------- |
| `colors.ts`   | Semantic color tokens | `colors.brand()`, `.success()`, `.error()`, `.warn()`, `.url()`, `.address()`                   |
| `icons.ts`    | Unified icon set      | `ICONS` — 20+ named unicode icons                                                               |
| `tty.ts`      | Environment detection | `isTTY()`, `isCI()`, `terminalWidth()`, `detectTerminal()`                                      |
| `spinner.ts`  | Animated spinner      | `Spinner` class — dots/line styles, succeed/fail, elapsed time                                  |
| `format.ts`   | Text formatters       | `formatDuration`, `formatGas`, `formatAddress`, `formatNumber`, `formatBytes`, `formatKeyValue` |
| `box.ts`      | Unicode box drawing   | `box(content, { title, padding, borderColor })`                                                 |
| `banner.ts`   | Branded banners       | `createBanner({ name, tagline, version })`, `createReadyBox({ entries, durationMs })`           |
| `logger.ts`   | Structured logger     | `Logger` — `.info()`, `.success()`, `.error()`, `.warn()`, `.step()`, `.header()`               |
| `table.ts`    | Column-aligned tables | `table(rows, { headers, border })`                                                              |
| `tasks.ts`    | Step-by-step runner   | `TaskList` — `[1/6]` pattern with spinner, bail/continue on error                               |
| `reporter.ts` | Base reporter class   | `BaseReporter` — abstract class with spinner, timing, verbose/json mode                         |
| `prompts.ts`  | Interactive prompts   | Re-exports `@clack/prompts` + `gottsIntro()`, `gottsOutro()`                                    |

## Dependency Rationale

| Choice            | Over     | Why                                                        |
| ----------------- | -------- | ---------------------------------------------------------- |
| `picocolors`      | chalk    | 3KB vs 44KB, identical API for our use case, no ESM issues |
| Custom `box()`    | boxen    | 70 lines vs heavy dep tree, only need light box drawing    |
| Custom `TaskList` | listr2   | 120 lines vs complex dep, we only need sequential tasks    |
| Custom `Spinner`  | ora      | 100 lines vs 30+ deps, already battle-tested in devenv     |
| `@clack/prompts`  | inquirer | Modern, beautiful, zero-config, ESM-first                  |

## Entrypoints

```typescript
// Main: everything except prompts
import {
  Spinner,
  Logger,
  box,
  table,
  createBanner,
  ICONS,
} from "@gotts.ai/tui";

// Prompts: interactive wizard flows
import {
  select,
  text,
  confirm,
  gottsIntro,
  gottsOutro,
} from "@gotts.ai/tui/prompts";
```

## Integration

The devenv package consumes tui via thin re-export wrappers:

* `devenv/src/cli/spinner.ts` → re-exports `Spinner` from tui
* `devenv/src/cli/format.ts` → re-exports formatters from tui
* `devenv/src/cli/themes.ts` → re-exports `ICONS` from tui, keeps domain-specific labels
* `devenv/src/cli/banner.ts` → calls `createBanner()` and `createReadyBox()` with devenv config
* `devenv/src/cli/reporter.ts` → `DevenvReporter extends BaseReporter` from tui