Skip to content

Commit dcd6433

Browse files
Rexclaude
Rex
and
claude
committed
docs(blog): add EN/JA/KO versions of Ink TUI refactor post + sync indices
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent e5a584a commit dcd6433

7 files changed

Lines changed: 391 additions & 1 deletion

File tree

‎blog-site/2026-04-rexcli-ink-tui-refactor.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: "RexCLI TUI Refactor: Modern Terminal UI with React Ink"
3+
description: "RexCLI migrated its TUI installer from manual string rendering to a React Ink + Ink UI component architecture, improving both the interactive experience and code maintainability."
4+
date: 2026-04-02
5+
tags: [RexCLI, TUI, Ink, React, Terminal, Onboarding]
6+
---
7+
8+
# RexCLI TUI Refactor: Modern Terminal UI with React Ink
9+
10+
The previous TUI installer used manual string concatenation to render the interface — high maintenance cost and a basic interactive experience. This refactor migrates it to a **React Ink + Ink UI** component architecture, making terminal interaction more modern.
11+
12+
## Why Refactor
13+
14+
The old TUI implementation had several problems:
15+
16+
- Manual ANSI string concatenation for colors and layout; changing one place easily broke others
17+
- No real component abstraction; state management scattered across the codebase
18+
- No routing concept; screen transitions written in a scattered way
19+
20+
Ink is a React renderer designed specifically for the terminal, enabling React component patterns for CLI interaction UIs. Combined with Ink UI's built-in components (`Select`, `TextInput`, `ConfirmInput`), development is greatly simplified.
21+
22+
## New Architecture
23+
24+
```
25+
scripts/lib/tui-ink/
26+
├── App.tsx # MemoryRouter + Routes configuration
27+
├── index.tsx # render() entry point
28+
├── hooks/
29+
│ └── useSetupOptions.ts # Shared configuration state
30+
├── screens/
31+
│ ├── MainScreen.tsx # Main menu
32+
│ ├── SetupScreen.tsx # Setup configuration
33+
│ ├── UpdateScreen.tsx # Update configuration
34+
│ ├── UninstallScreen.tsx # Uninstall configuration
35+
│ ├── DoctorScreen.tsx # Doctor configuration
36+
│ ├── SkillPickerScreen.tsx # Skill picker
37+
│ └── ConfirmScreen.tsx # Execution confirmation
38+
├── components/
39+
│ ├── Header.tsx # Top header bar
40+
│ ├── Footer.tsx # Bottom shortcut hints
41+
│ ├── Checkbox.tsx # Checkbox component
42+
│ └── ScrollableSelect.tsx # Scrollable selection list
43+
└── types.ts # Shared type definitions
44+
```
45+
46+
### Route Navigation
47+
48+
Screen switching is managed via `react-router`'s `MemoryRouter`:
49+
50+
```
51+
/ (MainScreen)
52+
→ /setup
53+
→ /update
54+
→ /uninstall
55+
→ /doctor
56+
57+
/setup → /skill-picker?owner=setup
58+
/setup → /confirm?action=setup
59+
60+
/skill-picker → Return to previous screen
61+
/confirm → Execute → Show result → Return to main menu
62+
```
63+
64+
### State Management
65+
66+
The `useSetupOptions` hook provides global configuration state shared across screens:
67+
68+
```typescript
69+
interface SetupOptions {
70+
components: {
71+
browser: boolean;
72+
shell: boolean;
73+
skills: boolean;
74+
superpowers: boolean;
75+
};
76+
wrapMode: 'all' | 'repo-only' | 'opt-in' | 'off';
77+
scope: 'global' | 'project';
78+
client: 'all' | 'codex' | 'claude' | 'gemini' | 'opencode';
79+
selectedSkills: string[];
80+
}
81+
```
82+
83+
### Custom Components
84+
85+
Ink UI's `Select` does not support scrollable window mode, so `ScrollableSelect` was implemented:
86+
87+
- Keyboard ↑/↓ navigation
88+
- Space to select
89+
- Grouped display (Core / Optional)
90+
- Skill descriptions and installed markers
91+
92+
## Dependencies
93+
94+
```bash
95+
npm install ink @inkjs/ui react react-router
96+
```
97+
98+
- `ink` 4.x — React renderer for terminal
99+
- `@inkjs/ui` — Built-in interactive components
100+
- `react` 18.x + `react-router` 7.x
101+
102+
Node version: project requires `>=22 <23`; Ink 4.x supports Node 18+, fully compatible.
103+
104+
## Visual Effects
105+
106+
- Current item: bold + cyan color
107+
- Installed marker: green `(installed)`
108+
- Description text: gray `dimColor`
109+
- Group headings: yellow or inverse
110+
- Error/success: red/green
111+
112+
## Compatibility
113+
114+
Non-interactive mode (no TTY) maintains the original CLI argument mode:
115+
116+
```bash
117+
aios setup --components browser,shell --scope global
118+
aios update --client codex
119+
aios doctor
120+
```
121+
122+
The entry point detects TTY and automatically invokes the Ink version.
123+
124+
## Related Links
125+
126+
- Ink docs: <https://github.com/vadimdemedes/ink>
127+
- Ink UI docs: <https://github.com/vadimdemedes/ink-ui>
128+
- Design doc: `docs/superpowers/specs/2026-04-02-ink-tui-design.md`
129+
- Implementation plan: `docs/superpowers/plans/2026-04-02-ink-tui-refactor.md`

‎blog-site/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Product documentation lives on `/` and the localized docs roots.
1616

1717
## Latest Posts
1818

19+
- [RexCLI TUI Refactor: Modern Terminal UI with React Ink](2026-04-rexcli-ink-tui-refactor.md)
1920
- [AIOS RL Training System: Multi-Environment Reinforcement Learning](rl-training-system.md)
2021
- [ContextDB Search Upgrade: FTS5/BM25 + Incremental Index Sync (P1.5)](contextdb-fts-bm25-search.md)
2122
- [Windows CLI Startup Stability Update](windows-cli-startup-stability.md)

‎blog-site/ja/2026-04-rexcli-ink-tui-refactor.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: "RexCLI TUI リファクタリング：React Ink によるモダンなターミナルUI"
3+
description: "RexCLI は手動の文字列レンダリングから React Ink + Ink UI コンポーネントアーキテクチャへ TUI インストーラーを移行し、対話体験とコードメンテ性を向上させました。"
4+
date: 2026-04-02
5+
tags: [RexCLI, TUI, Ink, React, Terminal, Onboarding]
6+
---
7+
8+
# RexCLI TUI リファクタリング：React Ink によるモダンなターミナルUI
9+
10+
これまでの TUI インストーラーは手動の文字列連結でインターフェースを描画しており、保守コストが高く対話体験もシンプルでした。今回のリファクタリングで **React Ink + Ink UI** コンポーネントアーキテクチャに移行し、ターミナルでの操作をよりモダンにします。
11+
12+
## なぜリファクタリングしたか
13+
14+
古い TUI 実装にはいくつかの問題がありました：
15+
16+
- 色やレイアウトのために ANSI 文字列を手動連結しており、一箇所を変えると他の場所にまで影響が広がりやすかった
17+
- コンポーネント抽象化ががなく、状態管理が各处に散らばっていた
18+
- ルーティングの概念がなく、画面遷移ロジックが散らばっていた
19+
20+
Ink はターミナル専用に設計された React レンダラーで、React コンポーネントパターンを使って CLI 操作インターフェースを記述できます。Ink UI の組み込みコンポーネント（`Select`、`TextInput`、`ConfirmInput`）を組み合わせることで、開発が大きく簡素化されます。
21+
22+
## 新アーキテクチャ
23+
24+
```
25+
scripts/lib/tui-ink/
26+
├── App.tsx # MemoryRouter + Routes 設定
27+
├── index.tsx # render() エントリーポイント
28+
├── hooks/
29+
│ └── useSetupOptions.ts # 共有設定状態
30+
├── screens/
31+
│ ├── MainScreen.tsx # メインメニュー
32+
│ ├── SetupScreen.tsx # セットアップ設定
33+
│ ├── UpdateScreen.tsx # 更新設定
34+
│ ├── UninstallScreen.tsx # アンインストール設定
35+
│ ├── DoctorScreen.tsx # Doctor 設定
36+
│ ├── SkillPickerScreen.tsx # スキル選択
37+
│ └── ConfirmScreen.tsx # 実行確認
38+
├── components/
39+
│ ├── Header.tsx # ヘッダー
40+
│ ├── Footer.tsx # フッターメニュー
41+
│ ├── Checkbox.tsx # チェックボックス
42+
│ └── ScrollableSelect.tsx # スクロール選択リスト
43+
└── types.ts # 共有型定義
44+
```
45+
46+
### ルートナビゲーション
47+
48+
画面切り替えは `react-router` の `MemoryRouter` で管理：
49+
50+
```
51+
/ (MainScreen)
52+
→ /setup
53+
→ /update
54+
→ /uninstall
55+
→ /doctor
56+
57+
/setup → /skill-picker?owner=setup
58+
/setup → /confirm?action=setup
59+
60+
/skill-picker → 前の画面に戻る
61+
/confirm → 実行 → 結果表示 → メインメニューに戻る
62+
```
63+
64+
### 状態管理
65+
66+
`useSetupOptions` フックが全局共有の設定状態を提供：
67+
68+
```typescript
69+
interface SetupOptions {
70+
components: {
71+
browser: boolean;
72+
shell: boolean;
73+
skills: boolean;
74+
superpowers: boolean;
75+
};
76+
wrapMode: 'all' | 'repo-only' | 'opt-in' | 'off';
77+
scope: 'global' | 'project';
78+
client: 'all' | 'codex' | 'claude' | 'gemini' | 'opencode';
79+
selectedSkills: string[];
80+
}
81+
```
82+
83+
### カスタムコンポーネント
84+
85+
Ink UI の `Select` はスクロールウィンドウモードをサポートしていないため、`ScrollableSelect` を実装：
86+
87+
- キーボード ↑/↓ ナビゲーション
88+
- Space キーで選択
89+
- グループ表示対応（Core / Optional）
90+
- スキル説明とインストール済みマーカー表示
91+
92+
## 依存ライブラリ
93+
94+
```bash
95+
npm install ink @inkjs/ui react react-router
96+
```
97+
98+
- `ink` 4.x — ターミナル用 React レンダラー
99+
- `@inkjs/ui` — 組み込みインタラクティブコンポーネント
100+
- `react` 18.x + `react-router` 7.x
101+
102+
Node バージョン：プロジェクト要件は `>=22 <23`、Ink 4.x は Node 18+ をサポートし完全互換。
103+
104+
## 視覚効果
105+
106+
- 現在の項目：太字 + cyan 色
107+
- インストール済みマーカー：緑色 `(installed)`
108+
- 説明テキスト：灰色 `dimColor`
109+
- グループヘッダー：黄色または inverse
110+
- エラー/成功：赤色/緑色
111+
112+
## 互換性
113+
114+
非対話モード（TTY なし）では従来の CLI 引数モードを維持：
115+
116+
```bash
117+
aios setup --components browser,shell --scope global
118+
aios update --client codex
119+
aios doctor
120+
```
121+
122+
エントリーポイントで TTY を検出し、自動的に Ink バージョンを呼び出します。
123+
124+
## 関連リンク
125+
126+
- Ink ドキュメント：<https://github.com/vadimdemedes/ink>
127+
- Ink UI ドキュメント：<https://github.com/vadimdemedes/ink-ui>
128+
- 設計ドキュメント：`docs/superpowers/specs/2026-04-02-ink-tui-design.md`
129+
- 実装計画：`docs/superpowers/plans/2026-04-02-ink-tui-refactor.md`

‎blog-site/ja/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ description: RexAI CLI エコシステム向けの成長・技術記事。
1616

1717
## 最新記事
1818

19+
- [RexCLI TUI リファクタリング：React Ink によるモダンなターミナルUI](2026-04-rexcli-ink-tui-refactor.md)
1920
- [AIOS RL Training System: Multi-Environment Reinforcement Learning](rl-training-system.md)
2021
- [ContextDB 検索アップグレード: FTS5/BM25 + 増分インデックス同期（P1.5）](contextdb-fts-bm25-search.md)
2122
- [Windows CLI Startup Stability Update](windows-cli-startup-stability.md)

0 commit comments

Comments
 (0)