cvc-tui

The Cognitive Version Control terminal UI — a React + Ink app that runs in your terminal and talks to the CVC Python core through a JSON-RPC gateway.

This package is a sidecar to the Python cvc wheel. It is built once with bun build --compile and the resulting single binary is embedded in the wheel (Slice 13). Users never npm install it directly.

Status

| Slice | What's in this package | | ----- | ---------------------- | | Slice 11 (this scaffold) | Build pipeline, banner, layout shell, store skeleton, gateway stub. | | Slice 12 | Streaming markdown renderer, slash commands, history. | | Slice 13 | Real JSON-RPC GatewayClient over stdio + bun --compile packaging. |

Architecture

┌─────────────────────────────────────────────────────────────┐
│  entry.tsx                                                  │
│   ├─ TTY check → fallback to plain banner                   │
│   ├─ GatewayClient.connect()    (stub today)                │
│   └─ render(<App/>) via Ink                                 │
│                                                             │
│  app.tsx                                                    │
│   └─ <AppLayout>                                            │
│        ├─ <Branding/>          banner + version + model     │
│        ├─ <TranscriptArea/>    nanostores: $messages        │
│        └─ <InputLine/>         <Thinking/> when busy        │
│                                                             │
│  app/uiStore.ts          ← terminal dims, focus, busy       │
│  app/turnStore.ts        ← messages, current turn lifecycle │
│  gateway/client.ts       ← STUB until Slice 11 wraps up     │
└─────────────────────────────────────────────────────────────┘

Why Ink + React 19?

• Ink 6 gives us flex layout, mouse, focus, raw-mode input, all over node streams.
• React 19 + the new compiler removes 90% of useMemo/useCallback ceremony.
• nanostores for state — zero boilerplate, surgical re-renders, no provider tree.

Why Bun?

• 3-5× faster cold start than tsx for the same TS sources.
• bun build --compile produces a single ~50 MB binary we ship inside the wheel.
• We still keep an npm/tsx fallback so contributors without Bun can hack on it.

CVC theme

| Token | Value | Usage | | ------- | --------- | ----- | | primary | #e63946 | banner, prompt arrow, assistant role tag | | dark | #0d1b2a | reserved for backgrounds when supported | | accent | #4a9eff | tagline, user role tag, secondary highlights | | dim | #6b7280 | placeholders, separators |

Assumes the user's terminal font is JetBrains Mono (or any Nerd Font with box-drawing + braille).

Scripts

bun install                # or: npm install
bun run dev                # or: npm run dev   (watches & reloads)
bun run build              # or: npm run build (compiles to dist/)
bun run test               # or: npm run test  (vitest)
bun run lint
bun run fmt

If bun is not on PATH, every script silently falls back to tsx / tsc.

Layout

src/
├── entry.tsx                # process bootstrap
├── app.tsx                  # root component tree
├── banner.ts                # CVC ASCII art + colour tokens
├── types.ts                 # shared TS types + theme constants
├── app/
│   ├── uiStore.ts           # nanostores: ui state
│   └── turnStore.ts         # nanostores: turn / transcript
├── components/
│   ├── appLayout.tsx        # flex root + resize tracking
│   ├── branding.tsx         # banner panel
│   ├── textInput.tsx        # ink-text-input wrapper
│   ├── streamingMarkdown.tsx# placeholder renderer (Slice 12)
│   └── thinking.tsx         # animated spinner
├── config/
│   └── timing.ts            # spinner / throttle constants
├── gateway/
│   └── client.ts            # JSON-RPC client STUB
└── __tests__/
    └── banner.test.ts

Beating Hermes

Where Hermes' ui-tui/ mixes a packages/hermes-ink workspace + Babel + a separate compile step, cvc-tui is a single Bun-built binary. No workspaces, no Babel pipeline, no tsx --watch in production. Cold start drops from ~700 ms (Hermes) to ~120 ms (target).

License

Same as the parent cvc project.