@uofx/cli 1.0.0

package/dist/infrastructure/errors/error-handler.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * 錯誤處理服務
+ *
+ * 提供統一的錯誤處理、格式化和日誌記錄功能
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorHandler = void 0;
+const tsyringe_1 = require("tsyringe");
+const tokens_1 = require("../../di/tokens");
+const app_error_1 = require("./app-error");
+const exit_codes_1 = require("./exit-codes");
+const error_formatter_util_1 = require("../utils/error-formatter.util");
+/**
+ * 錯誤處理器實作
+ */
+let ErrorHandler = class ErrorHandler {
+    constructor(logger, process) {
+        this.logger = logger;
+        this.process = process;
+        this.cleanupHandler = null;
+        this.cleanupOutput = null;
+        this.isCleaningUp = false;
+    }
+    /**
+     * 處理錯誤並退出程序
+     */
+    handleError(error, context) {
+        const appError = this.normalizeError(error, context);
+        // 如果正在清理中，不顯示錯誤也不退出 - 讓 SIGINT handler 管理退出
+        if (this.isCleaningUp) {
+            this.logError(appError);
+            // 保持 process 存活，等待 SIGINT handler 完成清理後退出
+            setInterval(() => { }, 1000);
+            return undefined;
+        }
+        const debug = this.isDebugMode();
+        // 顯示錯誤
+        console.error(this.formatError(appError, debug));
+        // 記錄日誌
+        this.logError(appError);
+        // 退出
+        this.process.exit(appError.exitCode);
+    }
+    /**
+     * 處理非致命錯誤（不退出程序）
+     */
+    handleWarning(error, context) {
+        const appError = this.normalizeError(error, context);
+        const debug = this.isDebugMode();
+        console.error(this.formatError(appError, debug));
+        this.logError(appError);
+    }
+    /**
+     * 設定全域錯誤處理器
+     */
+    setupGlobalHandlers() {
+        this.process.on('unhandledRejection', (reason) => {
+            const output = this.cleanupOutput;
+            // 如果正在清理中，不顯示錯誤訊息
+            if (!this.isCleaningUp) {
+                output?.newline().error('⚠️  Unhandled Promise Rejection detected').newline().flush();
+            }
+            const error = reason instanceof Error
+                ? reason
+                : new Error(`Unhandled rejection: ${String(reason)}`);
+            this.handleError(error, 'unhandledRejection');
+        });
+        this.process.on('uncaughtException', (error) => {
+            const output = this.cleanupOutput;
+            // 如果正在清理中，不顯示錯誤訊息
+            if (!this.isCleaningUp) {
+                output?.newline().error('⚠️  Uncaught Exception detected').newline().flush();
+            }
+            this.handleError(error, 'uncaughtException');
+        });
+        this.process.on('SIGINT', () => {
+            // 防止重複處理
+            if (this.isCleaningUp)
+                return;
+            this.isCleaningUp = true;
+            const output = this.cleanupOutput;
+            output?.newline().warning('Received interrupt signal...').flush();
+            // 抑制其他異步輸出，確保 cleanup 訊息清晰
+            output?.suppress();
+            const doCleanup = async () => {
+                if (this.cleanupHandler) {
+                    try {
+                        // 恢復輸出以顯示 cleanup 訊息
+                        output?.resume();
+                        output?.newline().section('Cleaning up...').flush();
+                        await this.cleanupHandler();
+                        output?.success('Cleanup completed').flush();
+                    }
+                    catch (error) {
+                        output?.warning(`Cleanup failed: ${(0, error_formatter_util_1.formatErrorMessage)(error)}`).flush();
+                    }
+                }
+                output?.newline().success('Exiting...').newline().flush();
+                this.process.exit(0);
+            };
+            // 使用 .then() 確保 Promise 被正確處理
+            doCleanup().catch(() => {
+                this.process.exit(1);
+            });
+        });
+        this.process.on('SIGTERM', () => {
+            const output = this.cleanupOutput;
+            output?.newline().success('Received termination signal, exiting...').newline().flush();
+            this.process.exit(0);
+        });
+    }
+    /**
+     * 註冊中斷清理 handler
+     */
+    registerCleanupHandler(handler, output) {
+        this.cleanupHandler = handler;
+        this.cleanupOutput = output ?? null;
+    }
+    /**
+     * 清除已註冊的清理 handler
+     */
+    clearCleanupHandler() {
+        this.cleanupHandler = null;
+        this.cleanupOutput = null;
+    }
+    // =========================================================================
+    // 私有方法
+    // =========================================================================
+    /**
+     * 將未知錯誤轉換為 AppError
+     */
+    normalizeError(error, context) {
+        if (error instanceof app_error_1.AppError) {
+            return error;
+        }
+        if (error instanceof Error) {
+            return new app_error_1.AppError(context ? `[${context}] ${error.message}` : error.message, {
+                cause: error,
+                exitCode: exit_codes_1.EXIT_CODES.UNKNOWN_ERROR,
+            });
+        }
+        return new app_error_1.AppError(context ? `[${context}] ${String(error)}` : String(error), {
+            exitCode: exit_codes_1.EXIT_CODES.UNKNOWN_ERROR,
+        });
+    }
+    /**
+     * 格式化錯誤訊息
+     */
+    formatError(error, debug) {
+        const lines = [];
+        // 錯誤訊息
+        // lines.push(`\n✗ Error: ${error.message}\n`);
+        // 解決方案
+        if (error.solution) {
+            lines.push(`\n  ! Solution: ${error.solution}\n`);
+        }
+        // Debug 資訊
+        if (debug) {
+            if (error.context) {
+                lines.push(`📋 Context: ${JSON.stringify(error.context, null, 2)}`);
+            }
+            if (error.stack) {
+                lines.push(`\nStack Trace:\n${error.stack}`);
+            }
+            if (error.cause) {
+                lines.push(`\nCaused by:\n${error.cause.stack || error.cause.message}`);
+            }
+        }
+        // 日誌位置
+        // lines.push(`\n📝 Full logs: ${this.logger.getLogFilePath()}\n`);
+        // 確保輸出後終端顏色恢復正常
+        return lines.join('\n');
+    }
+    /**
+     * 記錄錯誤到日誌
+     */
+    logError(error) {
+        this.logger.error(error, {
+            exitCode: error.exitCode,
+            solution: error.solution,
+            context: error.context,
+            system: {
+                nodeVersion: process.version,
+                platform: process.platform,
+                arch: process.arch,
+            },
+            skipConsole: true,
+        });
+    }
+    /**
+     * 判斷是否為 debug 模式
+     */
+    isDebugMode() {
+        return (process.env.LOG_LEVEL === 'debug' ||
+            process.env.UOFX_LOG_LEVEL === 'debug');
+    }
+};
+exports.ErrorHandler = ErrorHandler;
+exports.ErrorHandler = ErrorHandler = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(tokens_1.TOKENS.ILoggerPort)),
+    __param(1, (0, tsyringe_1.inject)(tokens_1.TOKENS.Internal.Process)),
+    __metadata("design:paramtypes", [Object, Object])
+], ErrorHandler);
+//# sourceMappingURL=error-handler.js.map

package/dist/infrastructure/errors/exit-codes.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_CODES = void 0;
+/**
+ * 標準退出碼定義
+ *
+ * 用於定義不同類型錯誤對應的程式退出碼
+ */
+exports.EXIT_CODES = {
+    /** 成功執行 */
+    SUCCESS: 0,
+    /** 一般錯誤 */
+    GENERAL_ERROR: 1,
+    /** 驗證錯誤（使用者輸入不符合規範） */
+    VALIDATION_ERROR: 2,
+    /** 環境錯誤 */
+    ENVIRONMENT_ERROR: 3,
+    /** 網路錯誤 */
+    NETWORK_ERROR: 4,
+    /** 業務邏輯錯誤 */
+    BUSINESS_ERROR: 5,
+    /** 系統錯誤（WSL、K8s 等系統層級問題） */
+    SYSTEM_ERROR: 6,
+    /** 未知錯誤 */
+    UNKNOWN_ERROR: 99,
+};
+//# sourceMappingURL=exit-codes.js.map

package/dist/infrastructure/errors/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * 統一錯誤系統匯出
+ *
+ * 這是整個應用程式錯誤處理的單一匯出點
+ * 使用方式:
+ *
+ * import {
+ *   ErrorHandler,
+ *   AppError,
+ *   EXIT_CODES
+ * } from '@/infrastructure/errors';
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_CODES = exports.ErrorHandler = exports.AppError = void 0;
+// 錯誤類別
+var app_error_1 = require("./app-error");
+Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return app_error_1.AppError; } });
+// 錯誤處理器
+var error_handler_1 = require("./error-handler");
+Object.defineProperty(exports, "ErrorHandler", { enumerable: true, get: function () { return error_handler_1.ErrorHandler; } });
+// 退出碼
+var exit_codes_1 = require("./exit-codes");
+Object.defineProperty(exports, "EXIT_CODES", { enumerable: true, get: function () { return exit_codes_1.EXIT_CODES; } });
+//# sourceMappingURL=index.js.map

package/dist/infrastructure/execution/builders/base-command.builder.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCommandBuilder = void 0;
+/**
+ * 基礎命令建構器
+ *
+ * 提供共用的 Fluent API 實作，子類別只需實作 buildActual() 方法
+ */
+class BaseCommandBuilder {
+    constructor(commandExecutor) {
+        this.commandExecutor = commandExecutor;
+        this.executable = '';
+        this.commandArgs = [];
+        this.isSensitiveInput = false;
+    }
+    /**
+     * 設定可執行檔名稱
+     */
+    setExecutable(executable) {
+        this.executable = executable;
+        return this;
+    }
+    arg(flag, value) {
+        if (value !== undefined) {
+            this.commandArgs.push({ type: 'safe', flag, value });
+        }
+        else {
+            this.commandArgs.push({ type: 'safe', value: flag });
+        }
+        return this;
+    }
+    sensitiveArg(flag, value) {
+        this.commandArgs.push({ type: 'sensitive', flag, value });
+        return this;
+    }
+    argIf(condition, flag, value) {
+        if (condition) {
+            this.arg(flag, value);
+        }
+        return this;
+    }
+    args(...values) {
+        values.forEach(v => this.arg(v));
+        return this;
+    }
+    stdin(input) {
+        this.stdinInput = input;
+        this.isSensitiveInput = false;
+        return this;
+    }
+    sensitiveStdin(input) {
+        this.stdinInput = input;
+        this.isSensitiveInput = true;
+        return this;
+    }
+    /**
+     * 建構用於記錄的安全命令字串
+     */
+    buildSafe() {
+        let cmd = this.buildCommandString(true);
+        // 子類別可能會覆寫此方法來加入額外的包裝
+        cmd = this.wrapCommand(cmd, true);
+        if (this.isSensitiveInput) {
+            cmd += ' < [STDIN: ***REDACTED***]';
+        }
+        return cmd;
+    }
+    /**
+     * 包裝命令（子類別可覆寫）
+     */
+    wrapCommand(command, _maskSensitive) {
+        return command;
+    }
+    /**
+     * 建構命令字串
+     */
+    buildCommandString(maskSensitive) {
+        const parts = [this.executable];
+        for (const arg of this.commandArgs) {
+            if (arg.type === 'sensitive' && maskSensitive) {
+                if (arg.flag) {
+                    parts.push(`${arg.flag} ***REDACTED***`);
+                }
+                else {
+                    parts.push('***REDACTED***');
+                }
+            }
+            else {
+                if (arg.flag && arg.value !== undefined) {
+                    parts.push(`${arg.flag} ${arg.value}`);
+                }
+                else if (arg.value !== undefined) {
+                    parts.push(arg.value);
+                }
+            }
+        }
+        return parts.join(' ');
+    }
+    /**
+     * 取得執行選項
+     */
+    getExecutionOptions() {
+        return {
+            command: this.buildActual(),
+            options: {
+                shell: true,
+                ...(this.stdinInput && { input: this.stdinInput }),
+            },
+            safeCommand: this.buildSafe(),
+        };
+    }
+    execSync(showOutput = false, suppressStderr = false) {
+        const { command, options, safeCommand } = this.getExecutionOptions();
+        return this.commandExecutor.execSync(command, options, showOutput, suppressStderr, safeCommand);
+    }
+    async exec(onStdout, onStderr) {
+        const { command, options, safeCommand } = this.getExecutionOptions();
+        return this.commandExecutor.exec(command, onStdout, onStderr, options, safeCommand);
+    }
+}
+exports.BaseCommandBuilder = BaseCommandBuilder;
+//# sourceMappingURL=base-command.builder.js.map

package/dist/infrastructure/execution/builders/host-command.builder.js

@@ -0,0 +1,58 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostCommandBuilder = exports.HostCommand = void 0;
+const tsyringe_1 = require("tsyringe");
+const tokens_1 = require("../../../di/tokens");
+const base_command_builder_1 = require("./base-command.builder");
+/**
+ * 主機命令實作
+ *
+ * 在主機上直接執行命令（不透過 WSL/SSH）
+ */
+class HostCommand extends base_command_builder_1.BaseCommandBuilder {
+    buildActual() {
+        return this.buildCommandString(false);
+    }
+    buildSafe() {
+        let cmd = this.buildCommandString(true);
+        if (this.isSensitiveInput) {
+            cmd += ' < [STDIN: ***REDACTED***]';
+        }
+        return cmd;
+    }
+}
+exports.HostCommand = HostCommand;
+/**
+ * 主機命令建構器
+ *
+ * 提供建立主機命令的基礎實作（跨平台）
+ */
+let HostCommandBuilder = class HostCommandBuilder {
+    constructor(commandExecutor) {
+        this.commandExecutor = commandExecutor;
+    }
+    create(executable) {
+        const builder = new HostCommand(this.commandExecutor);
+        builder.setExecutable(executable);
+        return builder;
+    }
+};
+exports.HostCommandBuilder = HostCommandBuilder;
+exports.HostCommandBuilder = HostCommandBuilder = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(tokens_1.TOKENS.Internal.ICommandExecutor)),
+    __metadata("design:paramtypes", [Object])
+], HostCommandBuilder);
+//# sourceMappingURL=host-command.builder.js.map

package/dist/infrastructure/execution/builders/windows-host-command.builder.js

@@ -0,0 +1,50 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WindowsHostCommandBuilder = void 0;
+const tsyringe_1 = require("tsyringe");
+const tokens_1 = require("../../../di/tokens");
+const host_command_builder_1 = require("./host-command.builder");
+/**
+ * Windows 主機命令建構器
+ *
+ * 繼承 HostCommandBuilder，添加 Windows 平台特定的命令建構方法
+ */
+let WindowsHostCommandBuilder = class WindowsHostCommandBuilder extends host_command_builder_1.HostCommandBuilder {
+    constructor(commandExecutor) {
+        super(commandExecutor);
+    }
+    powershell(command) {
+        const builder = new host_command_builder_1.HostCommand(this.commandExecutor);
+        builder.setExecutable('powershell');
+        builder.arg('-NoProfile');
+        builder.arg('-NoLogo');
+        builder.arg('-Command');
+        builder.arg(command);
+        return builder;
+    }
+    wslCmd(subcommand) {
+        const builder = new host_command_builder_1.HostCommand(this.commandExecutor);
+        builder.setExecutable('wsl');
+        builder.arg(subcommand);
+        return builder;
+    }
+};
+exports.WindowsHostCommandBuilder = WindowsHostCommandBuilder;
+exports.WindowsHostCommandBuilder = WindowsHostCommandBuilder = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(tokens_1.TOKENS.Internal.ICommandExecutor)),
+    __metadata("design:paramtypes", [Object])
+], WindowsHostCommandBuilder);
+//# sourceMappingURL=windows-host-command.builder.js.map

package/dist/infrastructure/execution/builders/wsl-command.builder.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WslCommandBuilder = void 0;
+const base_command_builder_1 = require("./base-command.builder");
+/**
+ * WSL 命令建構器
+ *
+ * 自動將命令包裝為 `wsl -d <instanceName> -- <command>` 格式
+ */
+class WslCommandBuilder extends base_command_builder_1.BaseCommandBuilder {
+    constructor(instanceName, commandExecutor) {
+        super(commandExecutor);
+        this.instanceName = instanceName;
+    }
+    buildActual() {
+        const innerCmd = this.buildCommandString(false);
+        return `wsl -d ${this.instanceName} -- ${innerCmd}`;
+    }
+    buildSafe() {
+        const innerCmd = this.buildCommandString(true);
+        let cmd = `wsl -d ${this.instanceName} -- ${innerCmd}`;
+        if (this.isSensitiveInput) {
+            cmd += ' < [STDIN: ***REDACTED***]';
+        }
+        return cmd;
+    }
+}
+exports.WslCommandBuilder = WslCommandBuilder;
+//# sourceMappingURL=wsl-command.builder.js.map