Game Saver

Hệ thống quản lý và đồng bộ save game trên cloud. Gồm web app (admin portal) và CLI tool chạy trực tiếp trong terminal.

🚀 Live Demo

• Web App: https://choi-cung-teppy.vercel.app
• CLI Tool: npx @duonghuyhieu/game-saver

Tính năng

• 🎮 Xem danh sách game - không cần đăng nhập
• 📥 Tải game - link tự động mở trong browser
• 💾 Backup save game lên cloud (Supabase Storage)
• 🔄 Đồng bộ save game giữa nhiều thiết bị
• ☁️ Download save public do admin chia sẻ
• ⚡ Tự động inject save vào thư mục game
• 🖥️ CLI thuần túy - chạy ngay trong terminal, không cần mở app riêng
• 🌐 Web Portal - quản lý saves, tải save trực tiếp trên web

Kiến trúc

web/
├── app/          # Next.js Web App (Admin + User Portal)
├── cli/          # Node.js CLI Tool
│   ├── index.ts          # CLI entry point
│   ├── config.ts         # API configuration
│   └── services/         # API client & file system
├── types/        # Shared TypeScript types
├── bin/          # CLI executable
└── components/   # React components

Tech Stack

• Web: Next.js 14, React, Supabase, Tailwind CSS
• CLI: Node.js, Inquirer, Chalk, Ora
• Database: Supabase (PostgreSQL)
• Storage: Supabase Storage
• Deploy: Vercel (web), NPM (CLI)

📚 Hướng dẫn sử dụng

👥 Cho người dùng (End Users):

• ⚡ Quick Start Guide - Bắt đầu trong 5 phút!
• 📖 Hướng dẫn đầy đủ - Hướng dẫn chi tiết từng bước

👨‍💻 Cho Developers:

Đọc tiếp phần Setup cho Developers bên dưới.

Cài đặt và Sử dụng

Người dùng: Chạy CLI ngay

npx @duonghuyhieu/game-saver

CLI sẽ chạy ngay trong terminal - không cần cài đặt!

 ██████   █████  ███    ███ ███████     ███████  █████  ██    ██ ███████ ██████
██       ██   ██ ████  ████ ██          ██      ██   ██ ██    ██ ██      ██   ██
██   ███ ███████ ██ ████ ██ █████       ███████ ███████ ██    ██ █████   ██████
██    ██ ██   ██ ██  ██  ██ ██               ██ ██   ██  ██  ██  ██      ██   ██
 ██████  ██   ██ ██      ██ ███████     ███████ ██   ██   ████   ███████ ██   ██

Quan ly va dong bo save game tren cloud

? Chon hanh dong: (Use arrow keys)
❯ [1] Chon game
  [2] Dang nhap
  [3] Dang ky
  [0] Thoat

Quy trình sử dụng CLI

Lần đầu sử dụng:

1. Chạy: npx @duonghuyhieu/game-saver
2. Chọn "[1] Chon game" để xem danh sách
3. Chọn game bạn muốn chơi
4. Chọn "[1] Tai game" để mở link download
5. Sau khi tải và cài game, quay lại CLI
6. Chọn "[2] Dang nhap" hoặc "[3] Dang ky"
7. Chọn "[2] Lay file save" để tải save public của admin (full progress!)

Backup save của bạn:

1. Chơi game và có progress
2. Chạy CLI và đăng nhập
3. Chọn game → "[3] Tai len file save"
4. Save tự động đọc từ thư mục game và upload lên cloud

Đồng bộ sang máy khác:

1. Chạy CLI trên máy mới
2. Đăng nhập cùng tài khoản
3. Chọn game → "[2] Lay file save"
4. Chọn save của bạn từ danh sách
5. Save tự động ghi vào thư mục game!

Setup cho Developers

1. Supabase Setup

a. Tạo Supabase Project

1. Đăng ký tại https://supabase.com
2. Tạo project mới
3. Lưu lại:
   • SUPABASE_URL
   • SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY

b. Chạy Database Schema

1. Mở SQL Editor trong Supabase Dashboard
2. Copy nội dung file supabase-schema.sql
3. Paste và chạy

c. Tạo Storage Bucket

1. Vào Storage trong Supabase Dashboard
2. Tạo bucket mới tên: save-files
3. Để public = false

2. Web App Setup (Local Development)

# Clone repository
git clone https://github.com/duonghuyhieu/choi-cung-teppy.git
cd choi-cung-teppy

# Copy environment file
cp .env.example .env.local

# Chỉnh sửa .env.local với Supabase credentials
# NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
# NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...
# SUPABASE_SERVICE_ROLE_KEY=eyJhbG...  ⚠️ QUAN TRỌNG: Cần thiết để upload files!
# JWT_SECRET=your-random-secret-key

# Install dependencies
npm install

# Run development server
npm run dev

Web app chạy tại: http://localhost:3000

3. Deploy Web App lên Vercel

# Push to GitHub (đã có git trong web/)
git push

Vercel Dashboard Setup:

1. Import repository từ GitHub

2. Không cần set Root Directory (project đã ở root)

3. ⚠️ QUAN TRỌNG: Add Environment Variables (Settings → Environment Variables):

   NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...
   SUPABASE_SERVICE_ROLE_KEY=eyJhbG...  👈 QUAN TRỌNG!
   JWT_SECRET=your-random-secret-key

   ⚠️ Lưu ý:

   • Phải thêm TẤT CẢ các biến này trước khi deploy
   • SUPABASE_SERVICE_ROLE_KEY cần thiết để upload files! Lấy từ Settings → API → service_role key
   • Copy từ file .env.local của bạn
   • Không bỏ sót biến nào, nếu không build sẽ bị lỗi!

4. Deploy!

Troubleshooting Vercel Build Errors:

Lỗi: "supabaseUrl is required"

• ✅ Kiểm tra đã add NEXT_PUBLIC_SUPABASE_URL trong Vercel Environment Variables chưa
• ✅ Redeploy sau khi thêm biến môi trường mới

Lỗi: "supabaseAnonKey is required"

• ✅ Kiểm tra đã add NEXT_PUBLIC_SUPABASE_ANON_KEY chưa

Tạo Admin User:

curl -X POST https://choi-cung-teppy.vercel.app/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "admin",
    "password": "your-secure-password",
    "role": "admin"
  }'

4. CLI Tool Setup

Development (Local)

# CLI sử dụng production URL mặc định: https://choi-cung-teppy.vercel.app
# Không cần tạo file .env nếu muốn dùng production

# Nếu muốn test với local development server:
echo "API_URL=http://localhost:3000" > cli/.env

# Run CLI
npm run cli

Production: Publish lên NPM

Package đã được chuẩn bị sẵn! Xem hướng dẫn chi tiết tại PUBLISH_NPM.md

Tóm tắt các bước:

1. ✅ Web app đã deploy tại: https://choi-cung-teppy.vercel.app
2. ✅ Production URL đã được cấu hình trong cli/config.ts
3. Build: npm run build:cli
4. Publish: npm publish --access public
5. User chạy: npx @duonghuyhieu/game-saver

Sử dụng

Web App (Admin)

1. Login vào https://choi-cung-teppy.vercel.app
2. Thêm games:
   • Tên game
   • Save path template: %APPDATA%/GameName/saves/*.sav
   • Download links
3. Upload public save files (optional)

CLI Tool (User)

1. Chạy CLI: npx @duonghuyhieu/game-saver
2. Chọn game từ danh sách (không cần đăng nhập!)
3. Tải game (nếu chưa có):
   • Chọn "Tai game" để xem download links
   • Link sẽ tự động mở trong trình duyệt
4. Quản lý save files (cần đăng nhập):
   • Lay file save: Tải save từ cloud và tự động ghi vào thư mục game
   • Tai len file save: Đọc save từ thư mục game và upload lên cloud
5. Đồng bộ nhiều máy:
   • Upload save từ máy 1
   • Download save về máy 2 với cùng tài khoản

Path Template Examples

Windows Game Pass:
%LOCALAPPDATA%/Packages/Microsoft.*/LocalState/*.sav

Steam:
%USERPROFILE%/Documents/My Games/GameName/*.sav

Epic:
%LOCALAPPDATA%/EpicGamesLauncher/Saved/SaveGames/*.sav

Custom:
%APPDATA%/GameName/saves/slot*.dat

Hỗ trợ wildcards * - sẽ match file đầu tiên tìm thấy.

API Endpoints

Authentication

POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me

Games

GET    /api/games
POST   /api/games            (admin only)
GET    /api/games/:id
PUT    /api/games/:id        (admin only)
DELETE /api/games/:id        (admin only)

Save Files

GET    /api/games/:id/saves
POST   /api/games/:id/saves
GET    /api/saves/:id
PUT    /api/saves/:id
DELETE /api/saves/:id

Features

CLI Features

✅ Browse games without login - xem danh sách game không cần đăng nhập ✅ Auto-open download links - tự động mở link trong browser ✅ Interactive menu - dùng arrow keys để navigate ✅ Persistent authentication - token lưu trong ~/.game-saver-token ✅ Auto save injection - tự động ghi save vào đúng thư mục game ✅ Auto save upload - tự động đọc save từ thư mục game ✅ Colored output - dễ đọc với chalk ✅ Loading spinners - feedback khi đang xử lý ✅ Auto path resolution - tự động tìm file theo template ✅ Error handling - thông báo lỗi rõ ràng

Web Features

✅ Browse all games - xem tất cả game và download links ✅ Download saves on web - tải save files trực tiếp trên web ✅ My Saves page - quản lý tất cả saves của bạn ✅ Public saves display - xem và tải save public trên game detail page ✅ JWT authentication - đăng nhập an toàn ✅ Admin panel - quản lý games, links và public saves (admin only) ✅ File upload/download - tải lên và tải xuống save files ✅ Row Level Security (RLS) - bảo mật dữ liệu với Supabase RLS

Bảo mật

• ✅ JWT authentication
• ✅ HTTP-only cookies
• ✅ Supabase RLS
• ✅ Admin role-based access
• ✅ Presigned URLs cho downloads
• ✅ Token stored locally (~/.game-saver-token)

Troubleshooting

Vercel Build Error: "supabaseUrl is required"

Nguyên nhân: Thiếu biến môi trường trên Vercel

Giải pháp:

1. Vào Vercel Dashboard → chọn project
2. Settings → Environment Variables
3. Thêm các biến sau:

   NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
   SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
   JWT_SECRET=your-jwt-secret

4. Deployments → chọn build mới nhất → Redeploy

CLI không connect được API

# Check API_URL
cat cli/.env

# hoặc hardcode trong cli/config.ts

Save file không inject được

• Kiểm tra path template có đúng không
• Chạy CLI với quyền Administrator (nếu cần write vào Program Files)

Upload save lỗi "new row violates row-level security policy"

Nguyên nhân: Service Role Key chưa được cấu hình

Giải pháp: Xem chi tiết tại FIX_UPLOAD_ERROR.md

Tóm tắt:

1. Lấy Service Role Key từ Supabase Dashboard (Settings → API)
2. Thêm vào .env.local: SUPABASE_SERVICE_ROLE_KEY=eyJhbG...
3. Chạy storage policies SQL (xem FIX_UPLOAD_ERROR.md)
4. Restart server

Upload save lỗi khác

• Kiểm tra file size < 50MB
• Kiểm tra bucket 'save-files' đã được tạo chưa

Requirements

• Node.js: 16+ (để chạy CLI)
• NPM: 8+ (để chạy NPX)
• OS: Windows (vì dùng %APPDATA% paths)

Cost (Free Tier)

• Supabase: 500MB DB + 1GB Storage → $0
• Vercel: 100GB Bandwidth → $0
• NPM: Unlimited downloads → $0

Total: $0/month ✅

License

MIT