galaxy-code 0.1.8 → 0.1.9

package/README.md

@@ -1,228 +1,431 @@
-# 🌌 Galaxy Code
+# Galaxy Code CLI
 
-**AI-Powered Coding Assistant** - An intelligent CLI tool that helps you build, analyze, and enhance your software projects with AI.
+**Galaxy Code** là một AI Agent CLI đa nhà cung cấp, được xây dựng với giao diện TUI tương tác — tương tự Claude Code nhưng hỗ trợ nhiều AI provider và có các tính năng context engineering nâng cao.
 
-[![npm version](https://img.shields.io/npm/v/galaxy-code.svg)](https://www.npmjs.com/package/galaxy-code)
-[![License](https://img.shields.io/npm/l/galaxy-code.svg)](https://github.com/buikevin/galaxy-code/blob/main/LICENSE)
-[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://galaxy-code-cli.vercel.app)
+```
+  ██████╗  █████╗ ██╗      █████╗ ██╗  ██╗██╗   ██╗
+ ██╔════╝ ██╔══██╗██║     ██╔══██╗╚██╗██╔╝╚██╗ ██╔╝
+ ██║  ███╗███████║██║     ███████║ ╚███╔╝  ╚████╔╝
+ ██║   ██║██╔══██║██║     ██╔══██║ ██╔██╗   ╚██╔╝
+ ╚██████╔╝██║  ██║███████╗██║  ██║██╔╝ ██╗   ██║
+  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝
+                         C O D E
+```
+
+---
+
+## Yêu cầu người dùng
+
+| # | Yêu cầu | Trạng thái |
+|---|---------|-----------|
+| 1 | Giao diện TUI tương tác như Claude Code | ✅ Hoàn thành |
+| 2 | Lệnh `galaxy-code` để khởi động CLI | ✅ Hoàn thành |
+| 3 | Lệnh `galaxy-code config` mở folder `~/.galaxy` | ✅ Hoàn thành |
+| 4 | Hỗ trợ 5 AI providers: Claude, Gemini, Ollama, Codex, Manual | ✅ Hoàn thành |
+| 5 | Đọc file: PDF, DOCX, XLSX/XLS, CSV, MD, TXT và các file code | ✅ Hoàn thành |
+| 6 | Sub AI Agent tóm tắt URD (User Requirements Document) | ✅ Hoàn thành |
+| 7 | Sub AI Agent review code sau khi AI viết xong (`/review`) | ✅ Hoàn thành |
+| 8 | Context Engineering: JIT Retrieval, Compaction, Structured Notes | ✅ Hoàn thành |
+| 9 | Config lưu tại `~/.galaxy/config.json` (macOS) | ✅ Hoàn thành |
+| 10 | Ba màn hình: Chat (F1), Plan (F2), Settings (F3) | ✅ Hoàn thành |
+
+---
 
-## 🚀 Quick Start
+## Cài đặt
 
-Install Galaxy Code globally:
+### Yêu cầu hệ thống
+
+- Node.js >= 18
+- pnpm >= 8
+
+### Cài đặt toàn cục
 
 ```bash
-npm install -g galaxy-code
+# Clone hoặc tải về project
+cd artifacts/galaxy-cli
+
+# Cài đặt dependencies
+pnpm install
+
+# Link binary toàn cục
+pnpm link --global
 ```
 
-Or run directly with npx:
+Sau khi link, bạn có thể gõ từ bất kỳ đâu:
 
 ```bash
-npx galaxy-code
+galaxy-code          # Khởi động TUI
+galaxy-code config   # Mở thư mục config
+galaxy-code urd <file>  # Phân tích URD
 ```
 
-## 📚 Documentation
+---
 
-Comprehensive documentation is available at: [https://galaxy-code-cli.vercel.app](https://galaxy-code-cli.vercel.app)
+## Sử dụng
 
-## 🎯 What is Galaxy Code?
+### Khởi động TUI
 
-Galaxy Code is an AI-powered coding assistant that helps developers:
+```bash
+galaxy-code
+```
 
-- **Create new projects** from scratch with AI planning
-- **Analyze existing projects** to understand codebase structure
-- **Add features** to existing applications intelligently
-- **Generate production-ready code** with best practices
-- **Manage development workflow** with integrated tools
+Giao diện TUI sẽ mở ra với ba màn hình điều hướng bằng phím tắt:
 
-Powered by advanced AI models and a comprehensive toolset, Galaxy Code acts as your AI pair programmer.
+| Phím | Chức năng |
+|------|-----------|
+| `F1` hoặc `Alt+1` | Màn hình Chat |
+| `F2` hoặc `Alt+2` | Màn hình Plan (các bước nhiệm vụ) |
+| `F3` hoặc `Alt+3` | Màn hình Settings |
+| `Ctrl+K` | Xóa lịch sử chat (reset cả session tracker) |
+| `?` hoặc `H` | Bật/tắt Help |
+| `Q` hoặc `Ctrl+C` | Thoát |
 
-## 🛠 AI Model Support
+### Slash Commands
 
-Galaxy Code supports multiple AI providers:
+Gõ trực tiếp vào ô chat:
 
-### Claude (Anthropic)
-- **Models**: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude Opus
-- **Features**: Full tool use support, streaming responses
-- **API Key**: `ANTHROPIC_API_KEY` environment variable
+| Lệnh | Chức năng |
+|------|-----------|
+| `/review` | Kích hoạt thủ công Code Reviewer Sub Agent — AI sẽ review toàn bộ file đã được viết/sửa trong session hiện tại |
+| `/diff` | Xem toàn bộ thay đổi của tất cả file AI đã sửa trong session (unified diff) |
+| `/diff <file>` | Xem chi tiết thay đổi của một file cụ thể, ví dụ: `/diff src/auth.ts` |
+| `/revert <file>` | Hoàn tác file về trạng thái trước khi AI sửa. Nếu AI tạo file mới → xóa file. Nếu AI sửa file cũ → khôi phục nội dung cũ |
 
-### Gemini (Google)
-- **Models**: Gemini 2.5 Flash and other Gemini models
-- **Features**: Tool calling, planning capabilities
-- **API Key**: `GOOGLE_AI_API_KEY` or `GEMINI_API_KEY` environment variable
+### Mở thư mục cấu hình
 
-### Ollama (Local)
-- **Models**: Any model hosted locally via Ollama
-- **Features**: Privacy-focused, offline development
-- **Setup**: Install Ollama and pull required models
+```bash
+galaxy-code config
+```
 
-## 🚀 Usage
+Lệnh này sẽ:
+1. In ra đường dẫn thư mục config
+2. Liệt kê các file trong thư mục
+3. Tự động mở File Manager (nếu có GUI)
 
-### Running Galaxy Code
+Vị trí config theo hệ điều hành:
+- **macOS**: `~/.galaxy/`
+- **Linux**: `~/.config/galaxy/`
+- **Windows**: `%APPDATA%\galaxy\`
 
-After installation, simply run:
+### Tóm tắt URD (User Requirements Document)
 
 ```bash
-galaxy-code
+galaxy-code urd ./requirements.pdf
+galaxy-code urd ./spec.docx
+galaxy-code urd ./requirements.md
 ```
 
-Or with npx (no installation required):
+Sub AI Agent sẽ:
+1. Đọc và phân tích file tài liệu
+2. Dùng AI provider đang cấu hình để tóm tắt
+3. Xuất ra cấu trúc gồm: Overview, Functional Requirements, Non-Functional Requirements, Stakeholders, Acceptance Criteria, Risks, Priority Recommendations
+4. Lưu kết quả tại `~/.galaxy/urd-summaries/<tên-file>-summary-<timestamp>.md`
+5. Thêm key points vào `~/.galaxy/NOTE.md` để dùng trong session tiếp theo
 
-```bash
-npx galaxy-code
+---
+
+## Cấu trúc thư mục `~/.galaxy/`
+
+```
+~/.galaxy/
+├── config.json          # Cấu hình agents, API keys
+├── NOTE.md              # Ghi chú ngữ cảnh persistent (Structured Notes)
+└── urd-summaries/       # Các bản tóm tắt URD được lưu tự động
+    └── spec-summary-2026-03-11T10-30-00.md
+```
+
+---
+
+## Cấu hình AI Providers
+
+Chỉnh sửa `~/.galaxy/config.json`:
+
+```json
+{
+  "agent": [
+    {
+      "type": "manual",
+      "apiKey": ""
+    },
+    {
+      "type": "claude",
+      "model": "claude-sonnet-4-5-20250929",
+      "apiKey": "sk-ant-..."
+    },
+    {
+      "type": "gemini",
+      "model": "gemini-2.5-flash",
+      "apiKey": "AIza..."
+    },
+    {
+      "type": "codex",
+      "model": "gpt-4o",
+      "apiKey": "sk-..."
+    },
+    {
+      "type": "ollama",
+      "model": "llama3.2",
+      "baseUrl": "http://localhost:11434"
+    }
+  ]
+}
 ```
 
-### CLI Options (Startup Flags)
+Hoặc chỉnh sửa trực tiếp trong Settings (F3) của TUI.
 
-| Flag             | Description                          | Default     |
-| ---------------- | ------------------------------------ | ----------- |
-| `--help`         | Show help information                | -           |
-| `--version`      | Display version                      | -           |
-| `--git`          | Enable git operations                | From config |
-| `--test`         | Enable test planning                 | From config |
-| `--config`       | Display current configuration        | false       |
-| `--reset-config` | Reset configuration to defaults      | false       |
-| `--dev`          | Enable development mode with DevTools| false       |
-| `--no-auto-update`| Disable auto-update on startup      | false       |
+### Các AI Provider hỗ trợ
 
-### In-App Commands
+| Provider | Mô tả | API Key |
+|----------|--------|---------|
+| **Manual** | Tự động kết nối Ollama tại `localhost:11434` | Không cần |
+| **Claude** | Anthropic Claude (claude-sonnet-4-5, claude-opus) | `ANTHROPIC_API_KEY` |
+| **Gemini** | Google Gemini (gemini-2.5-flash, gemini-pro) | `GOOGLE_API_KEY` |
+| **Codex** | OpenAI GPT-4o, GPT-4 | `OPENAI_API_KEY` |
+| **Ollama** | Local LLM (llama3.2, mistral, phi3, ...) | Không cần |
 
-While running Galaxy Code, you can use these commands:
+---
 
-| Command              | Description                                    |
-| -------------------- | ---------------------------------------------- |
-| `/help`              | Show available commands                        |
-| `/exit`              | Exit the application                           |
-| `/clear`             | Clear conversation history                     |
-| `/history`           | Show recent inputs (last 10)                   |
-| `/pwd`               | Show current working directory                 |
-| `/information`       | Display system information                     |
-| `/git true/false`    | Enable/disable git operations                  |
-| `/test true/false`   | Enable/disable test planning                   |
-| `/mode claude/gemini/ollama/manual` | Switch agent mode       |
-| `/config`            | Open configuration folder                      |
+## Công nghệ sử dụng
 
-### Example Usage
+### Core Framework
 
-```bash
-# Start with default settings
-$ galaxy-code
+| Package | Phiên bản | Mục đích |
+|---------|-----------|---------|
+| **@rezi-ui/core** | 0.1.0-alpha.59 | TUI rendering engine core |
+| **@rezi-ui/node** | 0.1.0-alpha.59 | Node.js backend cho Rezi |
+| **@rezi-ui/native** | 0.1.0-alpha.59 | Native C++ addon cho terminal rendering |
+
+**Rezi** (https://rezitui.dev) là framework TUI TypeScript hiện đại, tương tự React nhưng cho terminal. Sử dụng:
+- Worker thread architecture (rendering trong worker thread riêng biệt)
+- Native C++ addon cho hiệu suất cao
+- Reactive state management
+- Route-based navigation
 
-# Enable test planning from startup
-$ galaxy-code --test
+### Document Parsing
 
-# Display current configuration
-$ galaxy-code --config
+| Package | Phiên bản | Mục đích |
+|---------|-----------|---------|
+| **mammoth** | ^1.11.0 | Đọc file DOCX/DOC → plain text |
+| **pdf-parse** | ^1.1.1 | Đọc file PDF → plain text |
+| **xlsx** | ^0.18.5 | Đọc file Excel (XLSX/XLS/XLSM) → bảng markdown có cấu trúc |
 
-# Reset configuration to defaults
-$ galaxy-code --reset-config
+### Runtime & Build
 
-# Enable development mode
-$ galaxy-code --dev
+| Package | Phiên bản | Mục đích |
+|---------|-----------|---------|
+| **tsx** | ^4.21.0 | TypeScript execution (ts-node alternative) |
+| **typescript** | ~5.9.2 | Ngôn ngữ chính |
+| **Node.js** | >=18 | Runtime |
+
+---
+
+## Kiến trúc
+
+```
+artifacts/galaxy-cli/
+├── src/
+│   ├── cli.ts              # Entry point: xử lý argv (config, urd, TUI)
+│   ├── main.ts             # TUI app khởi tạo (Rezi createNodeApp)
+│   ├── types.ts            # TypeScript types chung
+│   ├── theme.ts            # Themes: Nord, Dark, Light
+│   │
+│   ├── agents/
+│   │   ├── runner.ts           # Điều phối AI call + tool execution + track file writes
+│   │   ├── claude.ts           # Anthropic Claude driver (streaming)
+│   │   ├── gemini.ts           # Google Gemini driver (streaming)
+│   │   ├── ollama.ts           # Ollama local driver (streaming)
+│   │   ├── codex.ts            # OpenAI Codex/GPT driver (streaming)
+│   │   ├── manual.ts           # Manual/auto-Ollama driver
+│   │   ├── urd-agent.ts        # Sub Agent: phân tích URD document
+│   │   ├── code-reviewer.ts    # Sub Agent: review code sau khi AI viết xong
+│   │   ├── session-tracker.ts  # Ghi lại file được viết/sửa trong session
+│   │   └── types.ts            # AgentDriver interface + system prompt
+│   │
+│   ├── config/
+│   │   ├── manager.ts      # Load/save config + platform path detection
+│   │   └── types.ts        # GalaxyConfig, AgentConfig interfaces
+│   │
+│   ├── context/
+│   │   ├── notes.ts        # Structured Notes: load/save ~/.galaxy/NOTE.md
+│   │   └── compaction.ts   # Context Compaction: tóm tắt khi >40 messages
+│   │
+│   ├── helpers/
+│   │   ├── keybindings.ts  # Ánh xạ phím → lệnh
+│   │   └── state.ts        # State management + reducers
+│   │
+│   ├── screens/
+│   │   ├── index.ts        # Route definitions cho Rezi
+│   │   ├── chat.ts         # Màn hình Chat (F1)
+│   │   ├── plan.ts         # Màn hình Plan (F2)
+│   │   ├── settings.ts     # Màn hình Settings (F3)
+│   │   └── shell.ts        # Shell command execution helper
+│   │
+│   └── tools/
+│       ├── file-tools.ts       # File tools: read, write, edit, grep (cross-platform), head, tail
+│       └── document-reader.ts  # Document parser: PDF, DOCX, XLSX/XLS, CSV, MD, TXT
+│
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## Tính năng Context Engineering
+
+### 1. Just-in-Time (JIT) Retrieval
+
+Thay vì load toàn bộ file vào context, AI sử dụng các tool để chỉ lấy phần cần thiết:
 
-# Disable auto-update
-$ galaxy-code --no-auto-update
 ```
+read_file(path, maxLines=200, offset=0)   # Đọc từng phần (có offset + giới hạn dòng)
+grep(pattern, path, contextLines=2)       # Tìm kiếm regex (native grep macOS/Linux, Node.js trên Windows)
+head(path, lines=50)                      # Đọc N dòng đầu
+tail(path, lines=50)                      # Đọc N dòng cuối
+list_dir(path)                            # Khám phá cấu trúc thư mục
+edit_file(path, old_string, new_string)   # Sửa phẫu thuật — chỉ thay đúng đoạn cần sửa
+read_document(path)                       # Đọc PDF / DOCX / XLSX / CSV — trả về bảng markdown có cấu trúc
+```
+
+### 2. Context Compaction
+
+Khi hội thoại vượt quá **40 tin nhắn**, hệ thống tự động:
+1. Tóm tắt 30 tin nhắn đầu thành một summary message
+2. Giữ nguyên 10 tin nhắn gần nhất
+3. Giải phóng context window cho tiếp tục
 
-### In-App Command Examples
+### 3. Structured Notes (`NOTE.md`)
+
+AI có thể ghi lại các thông tin quan trọng vào `~/.galaxy/NOTE.md`:
+- Ghi chú được load vào đầu mỗi session
+- Persistent qua các lần khởi động
+- URD summaries tự động append vào NOTE.md
+
+---
+
+## Sub AI Agent: URD Analyzer
+
+URD Agent là một sub-agent chuyên biệt, hoạt động độc lập với TUI:
 
 ```bash
-# Analyze current project
-> Analyze this project
+galaxy-code urd ./requirements.pdf
+```
 
-# Create a new Next.js application
-> Create a Next.js e-commerce app with TypeScript
+**Luồng hoạt động:**
+1. Đọc file (PDF/DOCX/MD/TXT) bằng document-reader
+2. Truncate tối đa 60.000 ký tự cho context window
+3. Tự động chọn AI provider tốt nhất đang có (theo thứ tự: Claude > Gemini > Ollama > Codex > Manual)
+4. Gửi document với system prompt chuyên biệt của senior requirements analyst
+5. Stream kết quả ra terminal
+6. Lưu tóm tắt vào `~/.galaxy/urd-summaries/`
+7. Append key points vào `NOTE.md` để dùng trong TUI session
 
-# Add authentication to existing project
-> Add JWT authentication to this app
+**Output bao gồm:**
+- Document Overview
+- Key Functional Requirements
+- Non-Functional Requirements  
+- Stakeholders
+- Acceptance Criteria
+- Risks & Assumptions
+- Priority Recommendations (top 3)
 
-# Ask technical questions
-> What are React hooks?
+---
 
-# Enable test planning
-> /test true
+## Sub AI Agent: Code Reviewer
 
-# Switch to Claude agent
-> /mode claude
+Code Reviewer là một sub-agent chuyên biệt, tự động kích hoạt sau khi AI viết hoặc chỉnh sửa code trong session.
 
-# Check system information
-> /information
+### Cách hoạt động
 
-# View command history
-> /history
+Trong suốt một session, hệ thống **Session Tracker** âm thầm ghi lại mọi file được AI tạo ra hoặc sửa đổi (qua `write_file` hoặc `edit_file`). Khi AI hoàn thành xong công việc, Code Reviewer tự động đọc lại toàn bộ danh sách file đó và gửi cho một AI instance riêng biệt — đóng vai senior code reviewer — để phân tích.
 
-# Exit the application
-> /exit
+```
+AI viết/sửa file  →  Session Tracker ghi nhận
+                                  ↓
+           AI hoàn thành nhiệm vụ / gõ /review
+                                  ↓
+           Code Reviewer đọc tất cả file trong session
+                                  ↓
+           Gửi cho AI (cùng provider) với prompt reviewer
+                                  ↓
+           Kết quả hiển thị trực tiếp trong Chat
 ```
 
-## 🏗 How It Works
+### Kích hoạt
 
-### 1. Project Analysis
+| Cách | Mô tả |
+|------|-------|
+| **Tự động** | Sau mỗi lần AI viết file và hoàn thành nhiệm vụ |
+| **Thủ công** | Gõ `/review` trong ô chat bất cứ lúc nào |
 
-Galaxy Code can analyze existing projects to understand:
+> Khi bạn gõ `Ctrl+K` để xóa chat, session tracker cũng được reset — file counter trở về 0.
 
-- Project structure and architecture
-- Technology stack in use
-- Key features and components
-- Potential improvement areas
+### Định dạng kết quả
 
-### 2. Feature-Driven Planning
+Code Reviewer trả về phân tích theo chuẩn sau, hiển thị ngay trong cửa sổ Chat:
 
-When creating or adding features, Galaxy Code follows a structured approach:
+```
+🔍 Code Review Result (N files)
 
-1. **Business Analysis** - Understands requirements and constraints
-2. **Technical Planning** - Creates implementation steps
-3. **Execution** - Generates code and runs necessary commands
-4. **Verification** - Optionally runs tests and code reviews
+- [CRITICAL] `src/auth.ts:42` — Token không được hash trước khi lưu DB. Dùng bcrypt.hash() thay vì lưu plain text.
+- [WARNING]  `src/api.ts:88`  — Thiếu xử lý trường hợp response.data là null, có thể gây crash runtime.
+- [INFO]     `src/utils.ts`   — Hàm formatDate() có thể dùng Intl.DateTimeFormat thay vì xử lý thủ công.
 
-### 3. Integrated Tool Execution
+⚠️ Issues found — 1 critical, 1 warning (cần sửa trước khi ship)
+```
 
-All file operations, git commands, and system calls are handled through integrated tools that:
+| Mức độ | Ý nghĩa |
+|--------|---------|
+| `[CRITICAL]` | Lỗi nghiêm trọng — bug, security hole, crash runtime. Phải sửa ngay |
+| `[WARNING]` | Vấn đề cần chú ý — edge case, code quality, có thể gây lỗi sau |
+| `[INFO]` | Gợi ý cải thiện — tùy chọn, không bắt buộc |
+| `✅ LGTM` | Không có vấn đề gì, code sạch |
 
-- Automatically create and modify files
-- Execute shell commands safely
-- Track progress and report results
-- Handle errors gracefully
+### Đặc điểm
 
-## 📋 Prerequisites
+- Dùng **cùng AI provider** với agent chính (không cần cấu hình thêm)
+- Hỗ trợ **mọi ngôn ngữ lập trình** — AI đọc được tất cả
+- Phân tích **cross-file**: phát hiện mâu thuẫn giữa các file với nhau
+- Giới hạn 8.000 ký tự/file để tránh vượt context window
 
-Before using Galaxy Code, ensure you have:
+---
 
-1. **Node.js** >= 18.14.1
-2. **AI Provider API Keys** (at least one):
-   - **Anthropic Claude**: `ANTHROPIC_API_KEY` for Claude models
-   - **Google Gemini**: `GOOGLE_AI_API_KEY` or `GEMINI_API_KEY` for Gemini models
-   - **Ollama**: Local installation with required models
+## Màn hình TUI
 
-### Environment Configuration
+### Chat (F1)
+- Nhập prompt và gửi đến AI agent đang active
+- Hiển thị streaming response theo thời gian thực
+- Hiển thị tool calls (read_file, grep, v.v.) và kết quả
+- Cuộn lịch sử hội thoại
 
-Create a `.env` file in your working directory with your API keys:
+### Plan (F2)
+- Hiển thị các task step được AI tự động extract từ response
+- Tracking trạng thái: pending → running → done/failed
+- Hỗ trợ hiển thị kế hoạch nhiều bước
 
-```env
-# Required (choose at least one)
-ANTHROPIC_API_KEY=your_anthropic_api_key_here
-GOOGLE_AI_API_KEY=your_google_api_key_here
-# or
-GEMINI_API_KEY=your_gemini_api_key_here
+### Settings (F3)
+- Chuyển đổi giữa các AI provider
+- Nhập/cập nhật API keys
+- Chọn model cho từng provider
+- Cài đặt auto-update
 
-# Optional
-OLLAMA_HOST=http://localhost:11434
-DEBUG=false
-```
+---
 
-## 📄 License
+## Phát triển
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+```bash
+# Chạy trong dev mode
+pnpm dev
 
-## 👨‍💻 Author
+# Type check
+pnpm typecheck
 
-**Kevin Bui (Bùi Trọng Hiếu)**
+# Chạy CLI entry point
+pnpm start
+```
 
-- Email: kevinbui210191@gmail.com
-- GitHub: [@kevinbui](https://github.com/kevinbui)
+---
 
-## 🙏 Acknowledgments
+## License
 
-- [Ink](https://github.com/vadimdemedes/ink) - React for interactive command-line apps
-- [Anthropic Claude](https://www.anthropic.com/claude) - Advanced AI models
-- [Google Gemini](https://ai.google.dev/) - AI orchestration
-- [Ollama](https://ollama.com/) - Local AI model serving
+MIT © Galaxy Code Project