procedure-cli 1.0.2 → 1.0.4

package/templates/ink-tui/INK-TUI-TECH-SPECS.md

@@ -0,0 +1,375 @@
+# Technical Specifications
+
+Technical stack, dependencies, configuration, and architecture for building CLI applications with React + Ink.js.
+
+Reference source: [Procedure CLI](https://github.com/ducban/procedure-cli.git)
+
+---
+
+## Dev Stack Summary
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| **Runtime** | Node.js | 22+ (ES2022 target) |
+| **Language** | TypeScript | ^5.8 (strict mode) |
+| **UI Framework** | React + Ink.js | React ^19.1 + Ink ^6.0 |
+| **UI Components** | @inkjs/ui | ^2.0 |
+| **Database** | SQLite (better-sqlite3) | ^11.8 |
+| **ID Generation** | nanoid | ^5.1 |
+| **Module System** | ESM (`"type": "module"`) | Node16 resolution |
+| **Build** | tsc (no bundler) | Native ES modules |
+| **Dev Server** | tsx (watch mode) | ^4.19 |
+| **Linting** | ESLint + @typescript-eslint | ^8.x |
+| **Testing** | Node.js built-in test runner | `node --test` |
+
+---
+
+## Core Dependencies
+
+### Production
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `react` | ^19.1.0 | Component model for UI rendering |
+| `ink` | ^6.0.0 | Terminal UI rendering engine — renders React components as terminal output |
+| `@inkjs/ui` | ^2.0.0 | Pre-built Ink components (TextInput, Spinner, etc.) |
+| `ink-spinner` | ^5.0.0 | Loading spinner animations |
+| `better-sqlite3` | ^11.8.1 | Synchronous SQLite database driver (no async overhead) |
+| `nanoid` | ^5.1.5 | Compact, URL-safe unique ID generation |
+
+### Development
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `typescript` | ^5.8.3 | TypeScript compiler |
+| `tsx` | ^4.19.4 | TypeScript execution with hot-reload for dev |
+| `@types/node` | ^22.15.0 | Node.js type definitions |
+| `@types/react` | ^19.1.2 | React type definitions |
+| `@types/better-sqlite3` | ^7.6.13 | better-sqlite3 type definitions |
+| `eslint` | ^8.57.1 | JavaScript/TypeScript linter |
+| `@typescript-eslint/parser` | ^8.56.1 | TypeScript parser for ESLint |
+
+---
+
+## TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "jsx": "react-jsx",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**Key settings:**
+- `"jsx": "react-jsx"` — uses the default React JSX runtime (no manual `import React` needed, though explicitly imported for clarity)
+- `"module": "Node16"` — ESM with `.js` extensions in imports
+- `"strict": true` — full strict mode (noImplicitAny, strictNullChecks, etc.)
+- `"target": "ES2022"` — modern JS features (top-level await, Array.at, etc.)
+
+---
+
+## Package.json Template
+
+```json
+{
+  "name": "your-cli-app",
+  "version": "0.1.0",
+  "description": "Your CLI app description",
+  "type": "module",
+  "files": ["dist", "config"],
+  "bin": {
+    "your-cli": "./dist/cli.js"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.tsx",
+    "dev:watch": "tsx watch src/cli.tsx",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "lint": "eslint src/ --ext .ts,.tsx",
+    "start": "tsx src/cli.tsx"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "better-sqlite3": "^11.8.1",
+    "ink": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "nanoid": "^5.1.5",
+    "react": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.0",
+    "@types/react": "^19.1.2",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^8.57.1",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+---
+
+## Build System
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Run in development mode (tsx, single run) |
+| `npm run dev:watch` | Run with hot-reload (tsx watch) |
+| `npm run build` | Compile TypeScript → `dist/` (tsc) |
+| `npm run typecheck` | Type-check without emitting files (fast) |
+| `npm run test` | Run tests with Node.js built-in test runner |
+| `npm run lint` | Lint all `.ts` and `.tsx` files |
+| `npm run start` | Run the app via tsx |
+
+**No bundler required** — uses native ES modules with Node.js. TypeScript compiles to `.js` files in `dist/`, imports use `.js` extensions throughout.
+
+---
+
+## Project Structure
+
+```
+project-root/
+├── src/
+│   ├── cli.tsx                     # Entry point — render(<App />) via Ink
+│   ├── app.tsx                     # Main app shell — menu-driven screen router
+│   ├── components/
+│   │   ├── banner.tsx              # ASCII art header with brand identity
+│   │   ├── timeline.tsx            # Vertical wizard with step indicators
+│   │   ├── step-indicator.tsx      # Animated step status (◆/◇/○)
+│   │   ├── gutter-line.tsx         # │  prefix component for content lines
+│   │   └── guttered-select.tsx     # Select + MultiSelect with gutter integration
+│   ├── screens/
+│   │   ├── [feature].tsx           # Feature screens (one file per screen)
+│   │   └── steps/
+│   │       └── [step].tsx          # Wizard step components (self-contained)
+│   └── lib/
+│       ├── theme.ts                # Color tokens — exports `C` object
+│       ├── themes/                 # Theme definitions (future: multiple themes)
+│       │   ├── index.ts            # Theme registry and loader
+│       │   ├── catppuccin-mocha.ts
+│       │   ├── catppuccin-latte.ts
+│       │   ├── tokyonight-dark.ts
+│       │   └── tokyonight-light.ts
+│       ├── types.ts                # All TypeScript types and interfaces
+│       ├── config.ts               # JSON config loader with validation
+│       ├── db.ts                   # SQLite CRUD (better-sqlite3, nanoid IDs)
+│       ├── csv.ts                  # CSV export utilities
+│       ├── validation.ts           # Input validation helpers
+│       └── input/
+│           └── normalize-keys.ts   # ANSI input normalization for deterministic key handling
+├── config/                         # JSON configuration files
+├── data/                           # SQLite database, backups, exports
+├── docs/
+│   ├── B3AWESOME-CLI-APP-UI-UX-GUIDELINE.md  # UI/UX design system
+│   ├── TECH-SPECS.md               # This file
+│   ├── PRD.md                      # Product requirements
+│   └── USER-STORIES.md             # User stories with acceptance criteria
+└── dist/                           # Compiled output (git-ignored)
+```
+
+---
+
+## Styling System
+
+### Color Token Architecture
+
+All colors are accessed through semantic tokens in `src/lib/theme.ts`:
+
+```typescript
+export const C = {
+  mauve:    '#...',   // brand, active focus, cursor highlight
+  green:    '#...',   // success, completed steps, confirmed values
+  yellow:   '#...',   // in-progress input highlight
+  sapphire: '#...',   // headings, section headers
+  teal:     '#...',   // secondary accent
+  red:      '#...',   // errors, destructive warnings
+  peach:    '#...',   // warnings
+  overlay1: '#...',   // gutter lines, dim text, hints, instructions
+  overlay0: '#...',   // pending steps, very dim elements
+  inputing: '#...',   // currently typing value
+  inputed:  '#...',   // confirmed/completed value
+  label:    '#...',   // general text labels, content
+} as const;
+```
+
+**Components import `C` — never hardcode hex values.** This enables theme switching.
+
+### Available Themes
+
+| Theme | Type | Token Source |
+|-------|------|-------------|
+| Catppuccin Mocha | Dark | [catppuccin.com](https://catppuccin.com) |
+| Catppuccin Latte | Light | [catppuccin.com](https://catppuccin.com) |
+| Tokyo Night | Dark | [github.com/enkia/tokyo-night-vscode-theme](https://github.com/enkia/tokyo-night-vscode-theme) |
+| Tokyo Night Light | Light | Same source |
+
+See `B3AWESOME-CLI-APP-UI-UX-GUIDELINE.md` §2 for complete hex values for all themes.
+
+---
+
+## UI Framework: React + Ink.js
+
+### How It Works
+
+Ink.js uses React's component model to render terminal output:
+
+```tsx
+// cli.tsx — Entry point
+import { render } from 'ink';
+import App from './app.js';
+
+render(<App />);
+```
+
+- React components render to **terminal characters** instead of DOM elements
+- `<Box>` = flex container (like `<div>` with flexbox)
+- `<Text>` = styled text (like `<span>` with color/bold)
+- All Ink components support `color`, `bold`, `dimColor`, etc.
+- Layout uses `flexDirection="column"` (vertical) or `flexDirection="row"` (horizontal)
+
+### Key Ink.js APIs
+
+| API | Purpose |
+|-----|---------|
+| `<Box>` | Flex container — `flexDirection`, `padding`, `margin`, `gap` |
+| `<Text>` | Styled text — `color`, `bold`, `dimColor`, `wrap` |
+| `useInput(handler)` | Keyboard input listener — receives `(input, key)` |
+| `useApp()` | App lifecycle — `exit()` to quit |
+| `render(<Component />)` | Mount React tree to terminal |
+
+### Key @inkjs/ui APIs
+
+| Component | Purpose |
+|-----------|---------|
+| `<TextInput>` | Text input field — `placeholder`, `defaultValue`, `onSubmit` |
+| `<Spinner>` | Loading spinner animation |
+| `<Select>` | Selection list (we use custom GutteredSelect instead) |
+
+---
+
+## Database Pattern
+
+### SQLite with better-sqlite3
+
+```typescript
+import Database from 'better-sqlite3';
+
+const db = new Database('data/assessments.db');
+db.pragma('journal_mode = WAL');          // Write-ahead logging
+db.pragma('foreign_keys = ON');           // Enforce FK constraints
+```
+
+**Key patterns:**
+- **Synchronous API** — no async/await needed, simpler code
+- **nanoid for IDs** — `nanoid()` generates compact unique IDs
+- **Prepared statements** — `db.prepare(sql).run(params)` for all queries
+- **Transactions** — `db.transaction(() => { ... })()` for multi-step operations
+- **Migrations** — detect columns via `PRAGMA table_info(tablename)`, alter as needed
+- **Result pattern** — all DB functions return `{ ok: true, data } | { ok: false, error: string }`
+
+### Migration Pattern
+
+```typescript
+function migrateIfNeeded() {
+  const columns = db.pragma('table_info(tablename)') as { name: string }[];
+  const hasNewColumn = columns.some((c) => c.name === 'new_column');
+  if (!hasNewColumn) {
+    db.exec('ALTER TABLE tablename ADD COLUMN new_column TEXT');
+  }
+}
+```
+
+---
+
+## Input Handling
+
+### ANSI Input Normalization
+
+Terminal input can arrive as batched ANSI sequences in a single stdin chunk. The normalizer handles:
+
+```typescript
+// CSI arrow sequences: \x1b[A (up), \x1b[B (down)
+// SS3 arrow sequences: \x1bOA (up), \x1bOB (down)
+// Enter/Return: \r, \n, \r\n
+```
+
+This prevents the "ghost selection" bug where rapid arrow key presses get misinterpreted.
+
+### Keyboard Shortcut Reference
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Move selection in lists |
+| `Enter` | Confirm/submit |
+| `Space` | Toggle in multi-select |
+| `Esc` | Return to main menu |
+| `Shift+Tab` | Go back (wizard steps, form fields) |
+
+---
+
+## Code Style
+
+| Rule | Convention |
+|------|-----------|
+| **Variables** | camelCase |
+| **Types/Interfaces** | PascalCase |
+| **File names** | kebab-case (`gutter-line.tsx`, `employee-step.tsx`) |
+| **Import order** | stdlib → external → internal |
+| **Error handling** | Return `Result<T>` objects, never throw |
+| **JSX runtime** | `react-jsx` (default React runtime) |
+| **Module imports** | Always use `.js` extension (ESM) |
+| **Strict mode** | TypeScript strict: true |
+
+### Result Pattern
+
+```typescript
+type Result<T> = { ok: true; data: T } | { ok: false; error: string };
+```
+
+All functions that can fail return this pattern. No try/catch at call sites — check `.ok` instead.
+
+---
+
+## Testing
+
+Uses Node.js built-in test runner:
+
+```bash
+# Run all tests
+node --import tsx --test "src/**/*.test.ts"
+
+# Run specific test
+node --import tsx --test -t "test name" "src/**/*.test.ts"
+```
+
+Test files are co-located with source: `src/lib/validation.test.ts` alongside `src/lib/validation.ts`.
+
+---
+
+## Verification Checklist
+
+Before every commit or PR:
+
+```bash
+npm run typecheck          # TypeScript type-checking (fast)
+npm run build              # Full compilation
+npm run lint               # ESLint
+npm run test               # Test suite
+```
+
+All four must pass clean.