port-sacred-terminal-ui-to-typescript-cli

Skill: Port Sacred Terminal UI to TypeScript CLI

Also available at https://sacred.computer/llm/skills/port-sacred-terminal-ui-to-typescript-cli/SKILL.md

Take a React Window*.tsx (or any sacred component) and produce a terminal CLI screen written in TypeScript that uses Simulacrum — the sacred CLI framework in scripts/cli/lib/.

See components/AGENTS.md for the canonical catalog of every sacred React component (props, theming tokens, CLI primitive equivalent). Read it before identifying which React surface you are porting from.

When to use

Use this skill whenever you want a CLI version of an existing sacred React surface. Sacred ships a small zero-dependency layout framework that maps every React <Card> / <DataTable> / <ActionButton> concept onto a CLI primitive. The output is identical to the React component minus the canvas-based animations — sacred renders are static.

What you ship

A single .ts file under scripts/cli/templates/ that:

1. Uses tsx as a shebang or npm run cli:typescript as the entry point.
2. Imports the framework primitives (import { ... } from '../lib/card').
3. Calls createApp({ build }).start() with a build(page, innerW, selectedRow) function that returns string[].

Reference implementation

Read these files before starting:

• scripts/cli/templates/template.ts — canonical example (run with npm run cli:typescript)
• scripts/cli/lib/ansi.ts — ANSI escapes, hex helpers, padding, gradient text
• scripts/cli/lib/window.ts — window frame (margin + window bg + shadow)
• scripts/cli/lib/card.ts — box-drawing card borders and word-wrap
• scripts/cli/lib/table.ts — formatRow, kvTable, kvTableGradient, ColSpec type
• scripts/cli/lib/button.ts — button, buttonRow
• scripts/cli/lib/app.ts — lifecycle: alt screen, raw mode, resize, paging, selection
• scripts/cli/colors.json — sacred-themed color palette (single source of truth)

React-to-CLI concept map

React surface	CLI primitive	Notes
<Card title="T">	cardTop('T', innerW) + cardBot(innerW)	Top + bottom borders
Content <div> inside <Card>	cardRow(text, innerW)	2ch left indent, padded to inner width
Key-value pair with gradient styling	kvTableGradient([[k, v]])	24ch key column, gradient on value
<thead><tr><td>	cardHeaderRow(formatRow(TH, COL_SPEC, innerW), innerW)	#585858 background
<tbody><tr><td>	cardRow(formatRow(row, COL_SPEC, innerW), innerW)	Per-cell alignment, status coloring
styles.statusOk/statusOff	colSpec: { status: true }	ACTIVE/OPEN/APPROVED → bold green; CLOSED/PAID/SUSPENDED → gray
<ActionButton hotkey="ESC">	button('ESC', 'exit')	Hotkey + label background pair
<RowSpaceBetween>	buttonRow(left, right, innerW)	Left + right justify with windowBg gap
Word-wrapped paragraph	wordWrap(text, innerW - 6)	Card padding is 3ch each side
Animated <ASCIICanvas> header	omit	Sacred CLI ports are static; the React side keeps the animation

ColSpec reference

type ColSpec = {
  width: number;
  align?: 'left' | 'right';
  grow?: boolean; // one column per spec absorbs extra width
  status?: boolean; // ACTIVE/OPEN/APPROVED → bold green; CLOSED/PAID/SUSPENDED → gray
  gap?: number; // inter-column spacing (default 1ch)
};

Step-by-step

1. Read the React file. Identify cards, tables, paragraphs, and button rows. Skip the <ASCIICanvas> (CLI is static).
2. Extract data. Move table rows into const arrays at the top of your TS file. If the React component already imports JSON, share the same JSON.
3. Define COL_SPECS. One per <table>. Mark a single column with grow: true.
4. Write build(page, innerW, selectedRow). Push cardTop → rows → cardBot for each section. Append buttonRow(...) last.
5. Run npm run cli:typescript. Verify margins, shadow, and inner padding match the React component.
6. Add interactivity (optional). Pass interactive: { count, onSelect, persist: true } to createApp and use cardSelectRow(content, innerW, i === selectedRow).
7. Add pagination (optional). Pass totalPages: N (or () => N) and slice your data by page inside build.

Formatting rules

• File starts with #!/usr/bin/env -S npx tsx.
• Comments use //NOTE(your_github_username): ....
• Column headers are UPPER_SNAKE_CASE.
• Dates are ISO 8601 (2026-04-08T09:00:00).
• Currency uses commas ($18,920.50).
• Never hardcode hex colors — read from scripts/cli/colors.json via the framework.

Smoke test

After writing the file:

npm test                  # JS framework + Python parity suite (chained)
npm run cli:typescript    # your screen renders, ESC quits cleanly

If npm test fails, the framework is broken — fix it before continuing. If your screen flickers on resize, you forgot to wrap content in cardRow/cardSelectRow (the framework relies on padded rows for the in-place redraw).

If a JS module changes the bytes coming out of any primitive, the parity test in scripts/python/sacred_cli/__tests__/test_parity.py will fail until the Python mirror under scripts/python/sacred_cli/ is updated to match. Port the change to both runtimes in the same PR — see skills/port-sacred-terminal-ui-to-python/SKILL.md § "Verifying parity".