@digiforce-nc/cli

Package	@digiforce-nc/cli
Depends on	@digiforce-nc/app

1) Tổng quan

@digiforce-nc/cli cung cấp lệnh digiforce - công cụ dòng lệnh chính để quản lý vòng đời ứng dụng Digiforce: khởi động, cài đặt, nâng cấp, quản lý plugin, và phát triển.

Vai trò

CLI là entry point duy nhất cho mọi tương tác với Digiforce từ terminal. Nó khởi tạo environment, tạo Application instance, rồi delegate sang các command handler tương ứng.

---

2) Bảng lệnh chính

Lifecycle commands

Lệnh	Mô tả	Ví dụ
digiforce dev	Khởi động development server với hot reload	digiforce dev --port 3000
digiforce start	Khởi động production server	digiforce start -d
digiforce install	Cài đặt ứng dụng: tạo bảng, seed dữ liệu	digiforce install
digiforce upgrade	Chạy migration và nâng cấp hệ thống	digiforce upgrade

Plugin management (pm)

Lệnh	Mô tả	Ví dụ
digiforce pm add <plugin>	Thêm plugin vào hệ thống	digiforce pm add @digiforce-nc/plugin-audit-logs
digiforce pm enable <plugin>	Kích hoạt plugin	digiforce pm enable audit-logs
digiforce pm disable <plugin>	Vô hiệu hóa plugin	digiforce pm disable audit-logs
digiforce pm remove <plugin>	Gỡ bỏ plugin	digiforce pm remove audit-logs
digiforce pm list	Liệt kê tất cả plugin và trạng thái	digiforce pm list

---

3) Flow xử lý lệnh

---

4) Utility functions

initEnv()

Đọc và merge các file environment theo thứ tự ưu tiên:

// Thứ tự load (sau override trước):
// 1. .env               - cấu hình mặc định
// 2. .env.local          - override cục bộ (git-ignored)
// 3. .env.[NODE_ENV]     - theo môi trường (development, production)
// 4. .env.[NODE_ENV].local

initEnv();
// Sau khi gọi, process.env chứa tất cả biến từ các file trên

Lưu ý

File .env.local và .env.*.local nên được thêm vào .gitignore. Chúng chứa secret riêng của từng developer/server.

checkDBDialect()

Kiểm tra và validate dialect database trước khi khởi động:

checkDBDialect();
// Throws nếu DB_DIALECT không hợp lệ
// Hỗ trợ: 'postgres', 'mysql', 'mariadb', 'sqlite'

buildIndexHtml()

Sinh file index.html cho client SPA, inject các biến cấu hình runtime:

await buildIndexHtml();
// Đọc template → inject API_BASE_URL, APP_NAME, etc. → ghi ra dist/

genTsConfigPaths()

Tự động sinh TypeScript path aliases cho workspace monorepo:

genTsConfigPaths();
// Scan packages/ → sinh tsconfig.paths.json
// Cho phép import '@digiforce-nc/server' thay vì đường dẫn tương đối

---

5) Environment setup

CLI đọc cấu hình từ environment variables. Các biến quan trọng:

Biến	Mô tả	Mặc định
APP_PORT	Cổng HTTP server	13000
APP_HOST	Host bind	0.0.0.0
DB_DIALECT	Loại database	sqlite
DB_HOST	Database host	localhost
DB_PORT	Database port	dialect-dependent
DB_DATABASE	Tên database	digiforce
DB_USER	Database user	-
DB_PASSWORD	Database password	-
DB_STORAGE	SQLite file path	./storage/db/digiforce.sqlite
APP_KEY	Secret key cho JWT/encryption	-
PLUGIN_PACKAGE_PREFIX	Prefix cho plugin package	@digiforce-nc/plugin-

Bắt buộc

APP_KEY phải được đặt trong production. Nếu thiếu, JWT token và encryption sẽ không an toàn.

---

6) Plugin generation helpers

CLI cung cấp tiện ích tạo scaffold cho plugin mới:

# Tạo plugin mới với template
digiforce pm create my-plugin

# Cấu trúc sinh ra:
# packages/plugins/my-plugin/
# ├── src/
# │   ├── server/
# │   │   ├── plugin.ts        # Server plugin class
# │   │   └── index.ts
# │   └── client/
# │       ├── index.tsx         # Client plugin entry
# │       └── locale/           # i18n files
# ├── package.json
# └── tsconfig.json

Plugin scaffold bao gồm:

• Server plugin class kế thừa Plugin với lifecycle hooks (afterAdd, beforeLoad, load, install)
• Client entry đăng ký routes, components, settings pages
• Locale files cho đa ngôn ngữ
• package.json với đúng peerDependencies

---

7) Kiến trúc CLI

Mở rộng

CLI sử dụng commander.js bên dưới. Các plugin có thể đăng ký command riêng thông qua app.cli.command() - xem Server Application.

• Mã nguồn