@uofx/cli 1.0.0

package/LICENSE

@@ -0,0 +1,40 @@
+# LICENSE
+
+Copyright (c) 2025 e-Excellence Inc. All rights reserved.
+
+This software (the "Software") is provided "as is", without any express or implied warranty, including, without limitation, warranties of merchantability, fitness for a particular purpose, or non-infringement.
+
+## License Grant
+
+Permission is hereby granted to any person obtaining a copy of this Software to install and execute it for **development, testing, and evaluation purposes only**.
+
+## Restrictions
+
+You may NOT:
+
+1.  Modify, decompile, reverse engineer, or disassemble the Software.
+2.  Redistribute, sublicense, or sell copies of the Software without prior written permission.
+3.  Use the Software to deploy, manage, or operate environments intended for production use.
+4.  Use the name of e-Excellence Inc. to endorse, promote, or market any product derived from this Software without specific prior written permission.
+
+## Third-Party Software Notice
+
+This Software may facilitate the installation or use of third-party software components, including but not limited to **Microsoft SQL Server Developer Edition**.
+
+1.  **Independent Licensing**: Such third-party software is licensed to you directly by its respective licensors (e.g., Microsoft) and is subject to their own license terms (EULA).
+2.  **Compliance**: You are solely responsible for complying with all license terms, restrictions, and usage policies of any third-party software installed by this tool.
+3.  **No Warranty**: e-Excellence Inc. does not grant any rights to, and makes no representations or warranties regarding, any third-party software.
+
+## User Notice Regarding SQL Server
+
+**WARNING: Strict Usage Limitations**
+
+1.  The Microsoft SQL Server Developer Edition installed by this tool is strictly limited by Microsoft for **development, testing, and demonstration purposes only**.
+2.  **Production Use Prohibited**: It may NOT be used in a production environment. Production use requires a separate, paid license from Microsoft.
+3.  You acknowledge that any violation of Microsoft's licensing terms is your sole responsibility.
+
+## Acknowledgment
+
+By using this Software, you agree to comply with the terms stated above. Any violation of this license or restrictions is at your own legal risk.
+
+---

package/README.md

@@ -0,0 +1,444 @@
+# UOFX CLI
+
+> 🚀 在 Windows WSL 環境中快速部署和管理 UOFX 開發環境的命令列工具
+
+---
+
+## ✨ 主要功能
+
+- ✅ **環境檢查與自動安裝** - 驗證系統需求，可自動安裝 WSL 環境
+- 🐳 **容器化隔離** - 使用 WSL + Kubernetes 建立完全隔離的開發環境
+- 🎯 **多實例管理** - 建立多個獨立環境，輕鬆切換專案
+- 📊 **即時狀態監控** - 查看實例運行狀態與資源使用
+- 🔐 **憑證管理** - 安全儲存並快速取得登入資訊
+- 📝 **詳細日誌** - 完整的操作記錄，協助除錯
+
+---
+
+## 📋 系統需求
+
+| 項目 | 需求 |
+|------|------|
+| 作業系統 | Windows 10/11 |
+| Node.js | 18.20.0 或更高版本 |
+| 記憶體 | 最低 16 GB |
+| 網路 | 需要連線至容器倉庫 |
+
+> **注意**：WSL 可透過 CLI 自動安裝（需系統管理員權限）
+
+---
+
+## 🚀 安裝
+
+```bash
+npm install -g @uofx/cli
+```
+
+驗證安裝：
+
+```bash
+uofx --version
+```
+
+---
+
+## 快速開始
+
+### 1️⃣ 環境檢查
+
+```bash
+uofx env setup
+```
+
+> 如果 WSL 未安裝，請以**系統管理員身份**執行此指令進行自動安裝
+
+### 2️⃣ 安裝開發環境
+
+```bash
+uofx env install --name dev
+```
+
+> ⏱️ **注意**：安裝過程需要下載容器映像檔，通常需要 **15 分鐘以上**，實際時間依網路速度而定。
+
+
+### 3️⃣ 取得連線資訊
+
+```bash
+uofx env list credentials --name dev --reveal
+```
+
+完成！現在你可以使用顯示的帳號密碼登入開發環境了。
+
+---
+
+## 💡 使用範例
+
+### 查看所有實例
+
+```bash
+uofx env list
+```
+
+輸出示例：
+```
+NAME  STATUS   VERSION  CHART VERSION  ADMIN URL                    SQL SERVER
+───────────────────────────────────────────────────────────────────────────────────
+dev   Running        2  2.100.002      http://[ip]:16888            [ip],30022
+test  Stopped        2  2.100.001      
+```
+
+### 多專案環境管理
+
+```bash
+# 建立專案 A 的環境
+uofx env install --name project-a
+
+# 建立專案 B 的環境
+uofx env install --name project-b
+
+# 切換到專案 A（會自動停止其他運行中的實例）
+uofx env start --name project-a
+
+# 停止實例
+uofx env stop --name project-a
+
+# 不再需要時刪除
+uofx env delete --name project-a
+```
+
+### 指定版本安裝
+
+```bash
+# 查看可用版本
+uofx env list charts
+
+# 安裝特定版本
+uofx env install --name dev --chart-version 1.2.0
+```
+
+### 除錯模式
+
+```bash
+# 啟用詳細日誌
+uofx config set --log-level debug
+
+# 查看日誌
+uofx logs --level DEBUG --since 10m
+
+# 過濾特定指令的日誌
+uofx logs --command env.install
+```
+
+---
+
+## 📖 指令參考
+
+### 環境管理 (env)
+
+#### `env setup`
+檢查並驗證系統環境，若 WSL 未安裝可自動進行安裝。
+
+```bash
+uofx env setup
+```
+
+> **注意**：若需要安裝 WSL，必須以系統管理員身份執行。
+
+#### `env install`
+安裝並部署 UOFX 開發環境。
+
+```bash
+uofx env install [選項]
+```
+
+> ⏱️ **安裝時間**：需要下載容器映像檔，通常需要 15 分鐘以上，實際時間依網路速度而定。
+
+**選項：**
+- `--name <name>` - 實例名稱（預設：`dev`）
+- `--chart-version <version>` - 指定 Helm chart（UOFX） 版本（預設：最新版本）
+
+**範例：**
+```bash
+# 使用預設名稱
+uofx env install
+
+# 指定名稱和版本
+uofx env install --name my-project --chart-version 1.2.0
+```
+
+#### `env list`
+顯示實例、憑證或相容版本資訊。
+
+```bash
+uofx env list [type] [選項]
+```
+
+**類型（type）：**
+- `instances` - 列出所有實例（預設）
+- `charts` - 列出相容的 chart（UOFX） 版本
+- `credentials` - 顯示實例憑證（需要 `--name`）
+
+**選項：**
+- `--name <name>` - 實例名稱（credentials 類型必填）
+- `--reveal` - 顯示完整憑證（搭配 credentials 使用）
+
+**範例：**
+```bash
+uofx env list                                  # 列出所有實例
+uofx env list charts                           # 列出相容的 UOFX 版本
+uofx env list credentials --name dev --reveal  # 查看完整憑證
+```
+
+#### `env start`
+啟動指定的 UOFX 實例。
+
+```bash
+uofx env start --name <name>
+```
+
+> **提示**：若有其他實例正在運行，CLI 會詢問是否停止該實例。
+
+#### `env stop`
+停止指定的 UOFX 實例。
+
+```bash
+uofx env stop --name <name>
+```
+
+#### `env delete`
+刪除指定的 UOFX 實例。
+
+```bash
+uofx env delete --name <name> [選項]
+```
+
+**選項：**
+- `-f, --force` - 跳過確認提示
+
+> ⚠️ **警告**：請務必使用此指令來刪除實例，**請勿**直接使用 `wsl --unregister` 指令。
+
+---
+
+### 設定管理 (config)
+
+#### `config list`
+列出所有設定值。
+
+```bash
+uofx config list [選項]
+```
+
+#### `config set`
+設定配置值。
+
+```bash
+uofx config set [選項]
+```
+
+**選項：**
+- `--log-level <level>` - 日誌等級（`debug`、`info`、`error`）
+- `--acr.name <name>` - ACR 名稱
+- `--acr.account <account>` - ACR 帳號
+- `--acr.password <password>` - ACR 密碼
+
+**範例：**
+```bash
+# 設定日誌等級
+uofx config set --log-level debug
+
+# 設定 ACR 連線資訊
+uofx config set --acr.name myregistry --acr.account user --acr.password secret
+```
+
+---
+
+### 日誌查看 (logs)
+
+查看和過濾 CLI 操作日誌。
+
+```bash
+uofx logs [選項]
+```
+
+**選項：**
+- `--lines <number>` - 顯示行數（預設：`50`）
+- `--level <level>` - 過濾日誌等級（`DEBUG`、`INFO`、`ERROR`）
+- `--since <range>` - 時間範圍（例如：`1h`、`2d`、`30m`）
+- `--correlation <id>` - 依關聯 ID 過濾
+- `--command <command>` - 依指令過濾（例如：`env.install`）
+- `--command-group <group>` - 依指令群組過濾（例如：`env`）
+
+**範例：**
+```bash
+uofx logs                           # 查看最近日誌
+uofx logs --level ERROR             # 只看錯誤
+uofx logs --since 1h                # 過去一小時的日誌
+uofx logs --command env.install     # 特定指令的日誌
+```
+
+---
+
+## ⚠️ 重要限制
+
+### 實例互斥
+
+**由於 WSL 架構限制，所有 WSL 實例共用同一個 IP 位址**，因此：
+
+- ⚠️ 同一時間只能有**一個**實例處於「執行中」狀態
+- ⚠️ 以下連接埠會被佔用，請確保沒有其他服務使用
+
+| 服務 | 連接埠 |
+|------|--------|
+| 前台網站 (HTTP) | 80 |
+| 前台網站 (HTTPS) | 443 |
+| 後台管理 (HTTP) | 16888 |
+| 後台管理 (HTTPS) | 16890 |
+| 手機入口 | 9000 |
+| SQL Server | 30022 |
+
+> 💡 **提示**：當啟動實例時，CLI 會自動檢測衝突並詢問是否停止其他實例
+
+### 與本機服務的連接埠衝突
+
+如果您的 Windows 主機上有其他服務正在使用相同連接埠（如 IIS、Apache、Nginx 等），將會發生衝突。
+
+**解決方式：停用 localhost 轉發**
+
+如果您需要同時運行本機服務和 UOFX，可以停用 WSL 的 localhost 轉發功能。
+
+**步驟：**
+
+1. 在 Windows 使用者目錄建立 `.wslconfig` 檔案：
+   ```powershell
+   notepad $env:USERPROFILE\.wslconfig
+   ```
+
+2. 加入以下內容：
+   ```ini
+   [wsl2]
+   localhostForwarding=false
+   ```
+
+3. 重啟 WSL：
+   ```powershell
+   wsl --shutdown
+   ```
+
+4. 重新啟動 UOFX 實例：
+   ```bash
+   uofx env start --name dev
+   ```
+
+**使用 WSL IP 存取：**
+
+停用 localhost 轉發後，您需要使用 WSL 的實際 IP 位址來存取服務：
+
+```bash
+# 查看實例資訊（包含 IP）
+uofx env list
+
+# 輸出範例：
+# NAME  STATUS   VERSION  ADMIN URL              SQL SERVER
+# dev   Running        2  http://[IP]:16888      [IP],30022
+```
+
+**注意事項：**
+- ⚠️ 無法再使用 `localhost` 或 `127.0.0.1` 存取
+
+---
+
+## 🔧 常見問題
+
+### WSL 未安裝
+
+**問題**：執行 `uofx env setup` 顯示 Runtime 未安裝
+
+**解決方案**：
+1. 以**系統管理員身份**開啟 PowerShell
+2. 執行 `uofx env setup`
+3. 依照提示完成 WSL 安裝
+4. 重新啟動電腦
+
+### 記憶體不足
+
+**問題**：環境檢查顯示記憶體不足
+
+**解決方案**：
+- 關閉不必要的應用程式
+- 確保至少有 16 GB 可用記憶體
+
+### 實例無法啟動
+
+**問題**：`uofx env start` 執行失敗
+
+**解決方案**：
+```bash
+# 1. 檢查是否有其他實例運行
+uofx env list
+
+# 2. 停止衝突的實例
+uofx env stop --name <其他實例>
+
+# 3. 查看錯誤日誌
+uofx logs --level ERROR --since 5m
+```
+
+### 安裝過程中斷
+
+**問題**：安裝意外中斷
+
+**解決方案**：
+```bash
+# 刪除失敗的實例
+uofx env delete --name <實例名稱> --force
+
+# 重新安裝
+uofx env install --name <實例名稱>
+```
+
+### 取得詳細協助
+
+```bash
+# 啟用除錯模式
+uofx config set --log-level debug
+
+# 查看詳細日誌
+uofx logs --since 1h
+```
+
+---
+
+## 📚 運作原理
+
+本工具採用「容器化」概念來隔離開發環境：
+
+```mermaid
+flowchart LR
+    A[UOFX CLI] --> B[建立 WSL 實例]
+    B --> C[安裝 MicroK8s]
+    C --> D[部署 UOFX 服務]
+    D --> E[開發環境就緒]
+    
+    style A fill:#4CAF50
+    style E fill:#2196F3
+```
+
+**兩個主要步驟：**
+
+1. **建立 WSL 實例** - 在 Windows 上建立獨立的 Ubuntu 環境（類似輕量級虛擬機）
+2. **部署 UOFX 服務** - 在 WSL 內安裝 Kubernetes 並部署所有微服務
+
+**優點**：
+- ✅ 完全隔離，不影響本機環境
+- ✅ 可建立多個獨立實例
+- ✅ 刪除實例即可完全清除
+
+---
+
+## 📄 授權
+
+請參閱 [LICENSE](./LICENSE) 檔案
+
+---
+
+_UOFX CLI v1.0.0_