tui-v0

generate terminal uis from a prompt. ink first. batteries included.

what we are building

tui-v0 is a prompt-to-tui codegen cli. you type a goal like:

the tool:

1. turns your prompt into a structured tui schema
2. renders ink + react code from that schema
3. compiles it to a single runnable file
4. launches it in the same terminal tab
5. saves the app in ~/.tui-v0/apps/<name> so you can run or refine later

goals

• feel instant and safe out of the box
• schema first for deterministic regen and refinement
• ink target now, more targets later without breaking projects
• single-file runnable artifacts so users do not install per-app deps
• identical ux on mac, linux, and windows

core concepts

• tui schema: a tiny json spec that lists panes, lists, tables, keybindings, and data sources. models write this first. codegen reads it.
• targets: start with ink. add blessed and bubble tea later behind the same schema.
• app library: all generated apps live under ~/.tui-v0/apps. each app dir stores schema.json, design.md, app.tsx (source), app.mjs (compiled), and metadata.json.
• same-tab run: the runner spawns the compiled app with stdio inherited, so it feels like one flow.
• refine loop: tui-v0 --refine <name> "add fuzzy search" regenerates from the saved schema and prompt history.
• sandbox: by default the runtime scrubs env and sets the cwd to the app folder. future versions add fs allowlists.

commands that i want to implement

• tui-v0 "prompt..."
  generate, compile, run, and save.

• tui-v0 run <name>
  run a saved app.

• tui-v0 --refine <name> "delta prompt"
  apply changes and re-run.

• tui-v0 list
  list saved apps.

• tui-v0 --configure
  set provider keys and defaults.

repository layout

tui-v0/
├─ package.json
├─ tsconfig.json
├─ bin/tui-v0.js
├─ src/
│ ├─ cli/ # arg parsing and subcommands
│ ├─ config/ # paths and config store
│ ├─ schema/ # types and validation
│ ├─ ai/ # providers and prompts
│ ├─ codegen/ink/ # schema → ink tsx → compiled js
│ ├─ runtime/ # runner and sandbox
│ ├─ apps/ # saved app repo helpers
│ ├─ refine/ # refine flow
│ └─ utils/ # fs and process helpers
└─ test/

per-app layout on disk

~/.tui-v0/apps/<app_name>/
├─ app.tsx
├─ app.mjs
├─ schema.json
├─ design.md
├─ metadata.json
└─ logs/

how generation works

1. create a design brief from your prompt
2. produce a tui schema that matches the brief
3. generate ink components from the schema
4. compile the app with esbuild using bundle: true so react and ink are included in a single file
5. run the app, collect logs, and save artifacts

performance notes

• keep the ink tree shallow and stream fast areas via buffered regions
• prefer batched state updates
• compile to a single bundle to avoid per-app installs and startup cost

v0 shipping roadmap (lowercase)

why this order

start by making the non-ai plumbing rock solid: schema → codegen → compile → run → save. once this loop is reliable and deterministic, dropping in ai providers is safe and incremental.

step-by-step order to ship v0

1. repo bootstrap

• node 18+ target, tsconfig strict, eslint + type-aware rules, vitest setup, minimal ci for lint + test
• executable entry wired: bin/tui-v0.js with shebang and package bin field

2. config and paths

• define ~/.tui-v0/ layout and helpers to resolve, create, and guard folders (apps/, logs/, tmp/)
• add simple json config store for defaults and provider keys (not used yet)

3. schema (no ai yet)

• define zod types for the tui schema and strict validation
• add tui-v0 --from-schema <file> so the whole pipeline runs without ai
• include a small templates/examples/ folder of valid schemas for testing

4. ink target codegen

• implement schema → app.tsx renderer (pure functions, deterministic)
• store ejs/tsx fragments in codegen/ink/files and compose in code, avoid stringly-typed glue

5. compiler

• compile with esbuild bundle: true, platform: node, format: esm to a single app.mjs
• verify react + ink are included and the output runs with plain node app.mjs

6. runtime

• spawn compiled app with inherited stdio (same-tab), forward ctrl+c, handle exit codes
• sandbox: scrub env by default, cwd to the app folder, optional allowlist later
• stream logs into logs/ under the app directory

7. app library

• save-app(name, schema, sources, bundle, metadata) and list, get, remove
• metadata: name, created_at, command_history, version, target

8. cli commands

• tui-v0 "prompt..." (temporarily accepts --from-schema for pre-ai)
• tui-v0 run <name>
• tui-v0 --refine <name> "delta" (pre-ai: apply structured deltas, later: ai-assisted)
• tui-v0 list
• tui-v0 --configure

9. tests and examples

• snapshot tests for schema validation and codegen output
• golden-file test for compiler and a smoke run of an example

10. docs and polish

• quickstart, examples, troubleshooting, performance notes
• telemetry: none by default; if added later, clear opt-in

11. release

• npm version, changelog, publish dry-run, real publish
• create a minimal npx tui-v0 "hello" demo that runs end-to-end locally

pre-ai checklist (do this first)

• schema is fully specified in zod with defaults and docs
• pipeline works end-to-end with --from-schema (no network)
• codegen produces readable app.tsx with stable formatting
• compile step creates a single-file app.mjs that runs with node without extra installs
• runner saves artifacts and logs under ~/.tui-v0/apps/<name> and re-runs correctly
• cli has help, version, error messages, and nonzero exit codes on failure
• unit tests cover: schema validation, a small codegen sample, compile success, run success
• repo has examples: at least 3 schemas (list, table, multi-pane)

when to add ai providers

after the pre-ai checklist is green, add the minimal ai surface:

• provider interface in src/ai/providers: generate_design_brief(prompt), generate_schema(brief), apply_delta(prev_schema, delta_prompt)
• start with a single provider (e.g., openai) behind env vars managed by --configure
• keep prompts in src/ai/prompts and snapshot their outputs in tests with seed inputs
• ensure ai is optional: if missing keys, the cli guides users to --from-schema or --configure

developer workflow (scaffold)

• pnpm|npm install
• npm run lint && npm run test
• run an example schema end-to-end:
  • tui-v0 --from-schema templates/examples/list.json
  • verify it generates, compiles, runs, and saves to ~/.tui-v0/apps/<name>

definition of done for v0

• users can: generate from schema, run, list, rerun saved apps, and refine via structured deltas
• a single ink app bundles and runs as app.mjs without per-app deps
• documentation shows quickstart and troubleshooting
• basic tests pass in ci; mac/linux confirmed locally