🎭 Chan MengInteractive CLI Experience

An NPX-executable CLI application that introduces Chan Meng through an interactive, story-driven terminal experience. Experience minimalist philosophy through an elegant command-line interface. One-click FREE execution via NPX - no installation required.

Tech Stack Badges:

[!TIP] This project demonstrates minimalist CLI design with modern JavaScript. It combines interactive storytelling with elegant terminal UX to create an engaging personal introduction experience.

📸 Screenshots & Demo

🎬 Demo Video

https://github.com/user-attachments/assets/66d9844c-bce6-4cd2-844b-022f672f7cbb

🖼️ Interface Showcase

TOC

• ✨ Key Features
• 🚀 Quick Start
  • Run via NPX (Recommended)
  • Run from Source
• 📦 Requirements
• 🎯 Interactive Modules
• 🛠️ Tech Stack
• 🏗️ Project Structure
• ⚙️ Configuration
• ⌨️ Development
  • Install Dependencies
  • Run Tests
  • Build for Distribution
• 📊 Technical Highlights
• 🤝 Contributing
• 📄 License
• 👤 Author

✨ Key Features

1 Interactive Story-Driven Experience

Experience a curated journey through Chan's minimalist philosophy via an elegant CLI interface with beautiful ASCII art and gradient colors.

Key capabilities include:

• 🚀 Quick Tour Mode: A curated 3-minute introduction
• 📚 Full Experience Mode: Explore all modules at your own pace
• 💾 Smart Progress Tracking: Automatically saves and resumes your journey
• 🎨 Beautiful Terminal UI: ASCII art, gradient colors, and boxed content
• ♿ Universal Accessibility: Graceful degradation for limited terminals

[!TIP] Run npx chan-meng anywhere, anytime - no installation required!

2 Minimalist Design Philosophy

Built with minimalist principles at its core - every dependency justified, every feature purposeful.

Design Principles:

• ✅ 7 Dependencies: Carefully selected within constitutional limit of 10
• ✅ Fast Startup: < 5 seconds with lazy loading for heavy modules
• ✅ ES Modules: Modern JavaScript with "type": "module"
• ✅ Zero Config: Works out of the box with sensible defaults

🚀 Quick Start

Run via NPX (Recommended)

npx chan-meng

🎉 That's it! The interactive experience will start immediately.

Run from Source

# Clone the repository
git clone https://github.com/ChanMeng666/chan-meng.git
cd chan-meng

# Install dependencies
npm install

# Build the Ink bundle, then run it
npm run build
npm start                # or: node dist/cli.js

# Or develop with watch-mode rebuilds
npm run dev              # in one terminal
node dist/cli.js         # in another, after each change

📦 Requirements

[!IMPORTANT] Ensure you have the following:

• Node.js: 22.0.0 or higher (Download)
• Terminal: Minimum 80x24 characters
• Recommended: A terminal with color support and Unicode/emoji (Windows Terminal, iTerm2, GNOME Terminal)

🎯 Interactive Modules

The CLI experience is organized into four interactive modules:

| Module | Description | Duration | |--------|-------------|----------| | 🗺️ The Journey | Chan's path from family constraints to minimalist freedom | ~5 min | | 💭 Philosophy | Core minimalist beliefs and principles | ~4 min | | ✂️ Practical Minimalism | Concrete examples of the minimalist lifestyle | ~3 min | | 📧 Connect | Get in touch with Chan Meng | ~1 min |

Quick Tour mode automatically selects the most impactful moments from each module for a 3-minute experience.

🛠️ Tech Stack

Runtime & Language:

• Node.js 22+: Modern JavaScript runtime
• ES2022 + JSX: Latest ECMAScript features with ES Modules, transpiled by esbuild

UI Framework:

• Ink ^7.0 — React renderer for the terminal. Layout uses Yoga (Flexbox), styling uses Ink <Text> / <Box> props.
• React ^19.2 — component model and useReducer state machine
• @inkjs/ui — <Select> for every menu / prompt

Configuration:

• conf ^11.0 — cross-platform preferences persistence

Build:

• esbuild (dev) — bundles src/ → dist/cli.js (single ESM file with shebang, Node 22 target)

[!TIP] Published tarball ships only dist/cli.js (≈1.8 MB single file), so npx chan-meng cold-starts with zero post-install work beyond the conf native-ish dep.

🏗️ Project Structure

chan-meng/
├── index.js                        # Shebang entry; forwards to src/cli.js
├── esbuild.config.js               # Bundle src/ → dist/cli.js (ESM, Node 22)
├── package.json
├── src/
│   ├── cli.js                      # Ink bootstrap shim (session + signals)
│   ├── App.jsx                     # <App/> reducer-backed state machine + routing
│   ├── components/                 # All UI as Ink/React components
│   │   ├── BigTitle.jsx            # ASCII banner with cyan→magenta gradient
│   │   ├── WelcomeScreen.jsx       # first screen — mode selection
│   │   ├── MainMenu.jsx            # module list for Full Experience
│   │   ├── QuickTour.jsx           # curated 3-min tour
│   │   ├── ModuleView.jsx          # generic segment walker
│   │   ├── ConnectView.jsx         # boxed contact card
│   │   ├── SegmentView.jsx         # title + content + metadata layout
│   │   ├── ClosingScreen.jsx       # thank-you / session duration
│   │   ├── FirstTimeTips.jsx
│   │   ├── Divider.jsx
│   │   ├── Prompt.jsx              # wrapper around @inkjs/ui <Select>
│   │   └── ErrorBanner.jsx
│   ├── state/
│   │   └── navigationReducer.js    # Pure reducer + action creators
│   ├── contexts/
│   │   └── CapabilitiesContext.js  # terminal caps, re-reads on resize
│   ├── hooks/
│   │   └── useCapabilities.js
│   ├── services/
│   │   └── progress.js             # visited/completed modules, session timing
│   ├── content/                    # Hardcoded module data (unchanged from v1)
│   │   ├── journey.js philosophy.js practical.js connect.js
│   │   ├── stories.js quick-tour.js
│   └── utils/
│       ├── terminal.js             # Terminal capability detection
│       └── config.js               # conf wrapper for persistence
├── tests/
│   ├── unit/                       # Component + reducer + service tests
│   └── integration/                # ink-testing-library scenarios
└── specs/                          # Original feature specs

⚙️ Configuration

User preferences and progress are automatically saved in:

| Platform | Configuration Path | |----------|-------------------| | Linux/macOS | ~/.config/chan-meng-cli/ | | Windows | %APPDATA%\chan-meng-cli\ |

Stored Data:

• Module completion status
• User preferences (tour mode, display settings)
• Last interaction timestamp

[!NOTE] To reset your progress, simply delete the configuration directory.

⌨️ Development

Install Dependencies

npm install

Run Tests

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

Build for Distribution

# Bundle src/ into dist/cli.js (runs automatically in prepublishOnly)
npm run build

# Dry-run the publish tarball to confirm shape
npm pack --dry-run       # shows README.md + LICENSE + package.json + dist/cli.js

# Test the package locally
npm pack && npx ./chan-meng-*.tgz

Development Scripts:

npm test          # Run Jest test suite (Ink + reducer + component snapshots)
npm run build     # Bundle via esbuild
npm run dev       # Watch-mode build
npm start         # Run dist/cli.js
npm pack          # Create tarball for distribution

📊 Technical Highlights

Performance Metrics:

• ⚡ < 5s Startup time (single-file bundle, no lazy loading needed)
• 🎯 80%+ Test coverage (lines) — unit tests for reducer + every component + integration snapshots via ink-testing-library
• 📦 3 Runtime Dependencies: ink, react, @inkjs/ui + conf (transitive deps included)
• 💨 ~350 KB compressed tarball / 1.8 MB unpacked

Code Quality:

• ✅ Ink + React: Declarative components with real reuse (12 shared UI components)
• ✅ useReducer state machine: Pure reducer, fully unit-testable without React
• ✅ Jest + ink-testing-library: Unit + integration coverage with lastFrame() assertions
• ✅ Spec-Driven Development: Built using Spec Kit methodology

Accessibility:

• ♿ Terminal Detection: Automatic capability detection
• 🎨 Graceful Degradation: Works on limited terminals
• 🌍 Universal Compatibility: Cross-platform support (Linux, macOS, Windows)

🤝 Contributing

Contributions are welcome! This project follows minimalist principles - every addition must justify its existence.

Development Process:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the existing code style and conventions
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Submit a pull request

Contribution Guidelines:

• Respect the constitutional limit of 10 dependencies
• Maintain startup time < 5 seconds
• Add meaningful tests (maintain 80%+ coverage)
• Update documentation as needed
• Follow the minimalist philosophy

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Open Source Benefits:

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed

👤 Author

Chan Meng - Senior AI/ML Infrastructure Engineer

• LinkedIn: chanmeng666
• GitHub: ChanMeng666
• Email: [email protected]
• Portfolio: chanmeng.org

⭐ Star this project • 📖 Read the Code • 🐛 Report Issues • 🤝 Contribute

Built with Spec-Driven Development using Spec Kit