aiexecode 1.0.111 → 1.0.113

package/src/system/session.js

@@ -12,7 +12,7 @@ import { TODO_WRITE_FUNCTIONS } from '../tools/todo_write.js';
 import { SKILL_FUNCTIONS } from '../tools/skill_tool.js';
 import { clampOutput, formatToolStdout } from "../util/output_formatter.js";
 import { buildToolHistoryEntry } from "../util/rag_helper.js";
-import { createSessionData, getLastConversationState, loadPreviousSessions, saveSessionToHistory, saveTodosToSession, restoreTodosFromSession, updateCurrentTodos, getCurrentTodos } from "./session_memory.js";
+import { createSessionData, getLastConversationState, loadPreviousSessions, saveSessionToHistory, saveTodosToSession, restoreTodosFromSession, saveTrimmedFileReadsToSession, restoreTrimmedFileReadsFromSession, updateCurrentTodos, getCurrentTodos } from "./session_memory.js";
 import { uiEvents } from "./ui_events.js";
 import { logSystem, logError, logAssistantMessage, logToolCall, logToolResult, logCodeExecution, logCodeResult, logIteration, logMissionComplete, logConversationRestored } from "./output_helper.js";
 import { requiresApproval, requestApproval } from "./tool_approval.js";
@@ -21,7 +21,7 @@ import { abortCurrentRequest } from "./ai_request.js";
 import { safeReadFile } from '../util/safe_fs.js';
 import { resolve } from 'path';
 import { createDebugLogger } from '../util/debug_log.js';
-import { ERROR_VERBOSITY } from '../config/feature_flags.js';
+import { loadSettings } from '../util/config.js';
 import {
     MAX_REASONING_ONLY_RESPONSES,
     DEFAULT_MAX_ITERATIONS,
@@ -825,6 +825,9 @@ export async function runSession(options) {
     // 세션 시작 알림
     uiEvents.sessionStart('Running agent session...');
 
+    // catch 블록에서도 접근 가능하도록 try 블록 밖에서 선언
+    let currentSessionData = null;
+
     try {
         // 현재 세션 데이터 생성
         const {
@@ -841,7 +844,7 @@ export async function runSession(options) {
         // previousSessions가 제공되지 않은 경우 자동으로 로드
         const sessionsToUse = previousSessions ?? await loadPreviousSessions(process.app_custom.sessionID);
 
-        const currentSessionData = createSessionData(process.app_custom.sessionID, mission);
+        currentSessionData = createSessionData(process.app_custom.sessionID, mission);
 
         // 파일 무결성 시스템에 현재 세션 ID 설정
         setCurrentSession(process.app_custom.sessionID);
@@ -887,6 +890,11 @@ export async function runSession(options) {
                 restoreTodosFromSession({ currentTodos: conversationState.currentTodos });
                 debugLog(`[runSession] Restored ${conversationState.currentTodos.length} todos from previous session`);
             }
+            // TrimmedFileReads 복원
+            if (conversationState.trimmedFileReads) {
+                restoreTrimmedFileReadsFromSession({ trimmedFileReads: conversationState.trimmedFileReads });
+                debugLog(`[runSession] Restored ${conversationState.trimmedFileReads.length} trimmed file reads from previous session`);
+            }
             // logSuccess('✓ Conversation state restored');
         } else {
             // logSystem('ℹ Starting with fresh conversation state');
@@ -1054,6 +1062,9 @@ export async function runSession(options) {
                 // Todos를 세션에 저장
                 saveTodosToSession(currentSessionData);
 
+                // TrimmedFileReads를 세션에 저장
+                saveTrimmedFileReadsToSession(currentSessionData);
+
                 debugLog(`[ITERATION ${iteration_count}] Saving session to history after completion_judge (mission_solved=${mission_solved})`);
                 await saveSessionToHistory(currentSessionData).catch(err => {
                     debugLog(`[ITERATION ${iteration_count}] Failed to save session after completion_judge: ${err.message}`);
@@ -1082,10 +1093,14 @@ export async function runSession(options) {
                 currentSessionData.orchestratorConversation = getOrchestratorConversation();
                 currentSessionData.orchestratorRequestOptions = null;
 
-                debugLog(`[ITERATION ${iteration_count}] Session interrupted - NOT saving session to history (disabled)`);
-                // await saveSessionToHistory(currentSessionData).catch(err => {
-                //     debugLog(`[ITERATION ${iteration_count}] Failed to save session: ${err.message}`);
-                // });
+                // 인터럽트 시에도 Todos와 TrimmedFileReads 저장 (다음 세션에서 복원 가능하도록)
+                saveTodosToSession(currentSessionData);
+                saveTrimmedFileReadsToSession(currentSessionData);
+
+                debugLog(`[ITERATION ${iteration_count}] Session interrupted - saving trimmedFileReads and todos`);
+                await saveSessionToHistory(currentSessionData).catch(err => {
+                    debugLog(`[ITERATION ${iteration_count}] Failed to save session on interrupt: ${err.message}`);
+                });
                 break;
             }
 
@@ -1119,6 +1134,21 @@ export async function runSession(options) {
                     : '✅ No function calls detected - mission complete';
                 uiEvents.addSystemMessage(message);
                 debugLog(`[ITERATION ${iteration_count}] ${message}`);
+
+                // completion_judge 없이 종료되는 경우에도 Todos와 TrimmedFileReads 저장
+                currentSessionData.completed_at = new Date().toISOString();
+                currentSessionData.mission_solved = true;
+                currentSessionData.iteration_count = iteration_count;
+                currentSessionData.toolUsageHistory = toolUsageHistory;
+                currentSessionData.orchestratorConversation = getOrchestratorConversation();
+                currentSessionData.orchestratorRequestOptions = null;
+                saveTodosToSession(currentSessionData);
+                saveTrimmedFileReadsToSession(currentSessionData);
+                debugLog(`[ITERATION ${iteration_count}] Saving session on no-function-call exit`);
+                await saveSessionToHistory(currentSessionData).catch(err => {
+                    debugLog(`[ITERATION ${iteration_count}] Failed to save session: ${err.message}`);
+                });
+
                 debugLog('========================================');
                 debugLog(`========== ITERATION ${iteration_count} END ==========`);
                 debugLog('========================================');
@@ -1158,12 +1188,17 @@ export async function runSession(options) {
         currentSessionData.orchestratorConversation = result.orchestratorConversation;
         currentSessionData.orchestratorRequestOptions = null; // 필요시 orchestrator에서 가져올 수 있음
 
-        debugLog(`[runSession] NOT saving final session to history (disabled - will only save after completion_judge) - sessionID: ${currentSessionData.sessionID}`);
+        // 루프 정상 종료 시에도 Todos와 TrimmedFileReads 저장
+        saveTodosToSession(currentSessionData);
+        saveTrimmedFileReadsToSession(currentSessionData);
+
+        debugLog(`[runSession] Saving final session to history - sessionID: ${currentSessionData.sessionID}`);
         debugLog(`[runSession] Session data size: ${JSON.stringify(currentSessionData).length} bytes`);
         debugLog(`[runSession] Final state - mission_solved: ${currentSessionData.mission_solved}, iteration_count: ${currentSessionData.iteration_count}`);
         debugLog(`[runSession] Tool usage history entries: ${currentSessionData.toolUsageHistory.length}`);
-        // 최종 세션 히스토리에 저장 (중복 저장이지만 최신 상태 보장) - DISABLED
-        // await saveSessionToHistory(currentSessionData);
+        await saveSessionToHistory(currentSessionData).catch(err => {
+            debugLog(`[runSession] Failed to save final session: ${err.message}`);
+        });
 
         debugLog('========================================');
         debugLog('========== runSession END ==========');
@@ -1179,9 +1214,13 @@ export async function runSession(options) {
         // 에러 메시지를 history에 표시 (한 번에 통합)
         const detailMessage = error?.error?.message || errorMessage;
 
+        // debug 설정 확인 (SHOW_API_PAYLOAD가 true면 verbose 모드)
+        const settings = await loadSettings().catch(() => ({}));
+        const isDebugMode = settings?.SHOW_API_PAYLOAD === true;
+
         let consolidatedErrorMessage;
-        if (ERROR_VERBOSITY === 'verbose') {
-            // 상세 모드: 모든 에러 정보 표시
+        if (isDebugMode) {
+            // 상세 모드 (/debug on): 모든 에러 정보 표시
             consolidatedErrorMessage = [
                 `[Session] Internal session error: ${errorType}`,
                 `  ├─ Message: ${detailMessage}`,
@@ -1192,12 +1231,41 @@ export async function runSession(options) {
                 `  └─ Stack trace: ${errorStack}`
             ].join('\n');
         } else {
-            // 간결 모드 (기본값): 에러 메시지만 표시
-            consolidatedErrorMessage = `[Session] Internal session error: ${detailMessage}`;
+            // 간결 모드 (기본값, /debug off): 사용자 친화적 에러 메시지
+            const statusNum = parseInt(errorStatus) || parseInt(error?.status);
+            let userFriendlyMessage;
+
+            if (statusNum === 503 || detailMessage.includes('503')) {
+                userFriendlyMessage = 'AI 서버가 일시적으로 응답하지 않습니다. 잠시 후 다시 시도해주세요.';
+            } else if (statusNum === 500 || detailMessage.includes('500')) {
+                userFriendlyMessage = 'AI 서버에서 오류가 발생했습니다. 잠시 후 다시 시도해주세요.';
+            } else if (statusNum === 401 || errorCode === 'invalid_api_key') {
+                userFriendlyMessage = 'API 키가 유효하지 않습니다. 설정을 확인해주세요.';
+            } else if (statusNum === 429) {
+                userFriendlyMessage = '요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.';
+            } else if (errorType === 'AbortError' || errorMessage.includes('aborted')) {
+                userFriendlyMessage = '요청이 취소되었습니다.';
+            } else {
+                userFriendlyMessage = '오류가 발생했습니다. 문제가 지속되면 /debug on 으로 상세 정보를 확인하세요.';
+            }
+
+            consolidatedErrorMessage = `[Session] ${userFriendlyMessage}`;
         }
 
         uiEvents.addErrorMessage(consolidatedErrorMessage);
 
+        // 에러 발생 시에도 Todos와 TrimmedFileReads 저장 시도
+        if (currentSessionData) {
+            currentSessionData.completed_at = new Date().toISOString();
+            currentSessionData.mission_solved = false;
+            saveTodosToSession(currentSessionData);
+            saveTrimmedFileReadsToSession(currentSessionData);
+            debugLog(`[runSession] Saving session on error`);
+            await saveSessionToHistory(currentSessionData).catch(err => {
+                debugLog(`[runSession] Failed to save session on error: ${err.message}`);
+            });
+        }
+
         // 에러를 throw하지 않고 정상적으로 종료
         return null;
     } finally {

package/src/system/session_memory.js

@@ -4,6 +4,7 @@ import { join, resolve } from 'path';
 import chalk from 'chalk';
 import { formatToolCall, formatToolResult, getToolDisplayName, getToolDisplayConfig } from './tool_registry.js';
 import { createDebugLogger } from '../util/debug_log.js';
+import { getTrimmedFileReads, setTrimmedFileReads } from './conversation_trimmer.js';
 
 const MAX_HISTORY_SESSIONS = 1; // 최대 보관 세션 수
 
@@ -11,7 +12,7 @@ const debugLog = createDebugLogger('session_memory.log', 'session_memory');
 
 // 현재 작업 디렉토리 기준 세션 디렉토리 경로 생성
 function getSessionDir(sessionID) {
-    return join(process.cwd(), '.aiexe', sessionID);
+    return join(process.cwd(), '.aiexe', 'sessions', sessionID);
 }
 
 // 세션 히스토리 파일 경로 생성
@@ -150,7 +151,8 @@ export function getLastConversationState(sessions) {
     return {
         orchestratorConversation: lastSession.orchestratorConversation || [],
         orchestratorRequestOptions: lastSession.orchestratorRequestOptions || null,
-        currentTodos: lastSession.currentTodos || []
+        currentTodos: lastSession.currentTodos || [],
+        trimmedFileReads: lastSession.trimmedFileReads || []
     };
 }
 
@@ -450,3 +452,29 @@ export function restoreTodosFromSession(sessionData) {
         currentSessionTodos = [];
     }
 }
+
+/**
+ * 세션 데이터에 trimmedFileReads를 저장
+ * @param {Object} sessionData - 세션 데이터 객체
+ */
+export function saveTrimmedFileReadsToSession(sessionData) {
+    debugLog('========== saveTrimmedFileReadsToSession ==========');
+    const trimmedFiles = getTrimmedFileReads();
+    debugLog(`Saving ${trimmedFiles.length} trimmed file reads to session`);
+    sessionData.trimmedFileReads = trimmedFiles;
+}
+
+/**
+ * 세션 데이터에서 trimmedFileReads를 복원
+ * @param {Object} sessionData - 세션 데이터 객체
+ */
+export function restoreTrimmedFileReadsFromSession(sessionData) {
+    debugLog('========== restoreTrimmedFileReadsFromSession ==========');
+    if (sessionData && Array.isArray(sessionData.trimmedFileReads)) {
+        debugLog(`Restoring ${sessionData.trimmedFileReads.length} trimmed file reads from session`);
+        setTrimmedFileReads(sessionData.trimmedFileReads);
+    } else {
+        debugLog('No trimmed file reads to restore');
+        setTrimmedFileReads([]);
+    }
+}

package/src/system/system_info.js

@@ -1,6 +1,7 @@
 import { exec } from "child_process";
 import { promisify } from "util";
 import { platform } from "os";
+import { readFileSync, existsSync } from "fs";
 
 const execAsync = promisify(exec);
 
@@ -23,6 +24,95 @@ function getOSType() {
     }
 }
 
+/**
+ * Linux 배포판 정보를 감지합니다.
+ * @returns {Promise<Object>} { id, name, version, packageManager }
+ */
+async function detectLinuxDistro() {
+    const result = {
+        id: 'unknown',
+        name: 'Linux',
+        version: '',
+        packageManager: null,
+        packageManagerName: ''
+    };
+
+    // /etc/os-release 파일에서 배포판 정보 읽기
+    try {
+        if (existsSync('/etc/os-release')) {
+            const content = readFileSync('/etc/os-release', 'utf8');
+            const lines = content.split('\n');
+
+            for (const line of lines) {
+                const [key, ...valueParts] = line.split('=');
+                const value = valueParts.join('=').replace(/^["']|["']$/g, '');
+
+                if (key === 'ID') result.id = value.toLowerCase();
+                if (key === 'NAME') result.name = value;
+                if (key === 'VERSION_ID') result.version = value;
+                if (key === 'ID_LIKE') result.idLike = value.toLowerCase();
+            }
+        }
+    } catch (e) {
+        // 파일 읽기 실패 시 무시
+    }
+
+    // 패키지 매니저 감지
+    const packageManagers = [
+        { cmd: 'apt', id: ['ubuntu', 'debian', 'linuxmint', 'pop', 'elementary', 'zorin', 'kali'], name: 'APT' },
+        { cmd: 'dnf', id: ['fedora', 'rhel', 'centos', 'rocky', 'alma', 'nobara'], name: 'DNF' },
+        { cmd: 'yum', id: ['centos', 'rhel', 'amazon'], name: 'YUM' },
+        { cmd: 'pacman', id: ['arch', 'manjaro', 'endeavouros', 'garuda'], name: 'Pacman' },
+        { cmd: 'zypper', id: ['opensuse', 'suse'], name: 'Zypper' },
+        { cmd: 'apk', id: ['alpine'], name: 'APK' },
+        { cmd: 'emerge', id: ['gentoo'], name: 'Portage' },
+        { cmd: 'brew', id: [], name: 'Homebrew' }  // fallback for any Linux with brew
+    ];
+
+    // 배포판 ID로 먼저 매칭
+    for (const pm of packageManagers) {
+        if (pm.id.includes(result.id) || (result.idLike && pm.id.some(id => result.idLike.includes(id)))) {
+            const hasCmd = await getCommandPath(pm.cmd);
+            if (hasCmd) {
+                result.packageManager = pm.cmd;
+                result.packageManagerName = pm.name;
+                break;
+            }
+        }
+    }
+
+    // ID 매칭 실패 시 설치된 패키지 매니저로 감지
+    if (!result.packageManager) {
+        for (const pm of packageManagers) {
+            const hasCmd = await getCommandPath(pm.cmd);
+            if (hasCmd) {
+                result.packageManager = pm.cmd;
+                result.packageManagerName = pm.name;
+                break;
+            }
+        }
+    }
+
+    return result;
+}
+
+/**
+ * macOS 버전 정보를 가져옵니다.
+ * @returns {Promise<Object>} { name, version }
+ */
+async function getMacOSInfo() {
+    const result = { name: 'macOS', version: '' };
+
+    try {
+        const { stdout } = await execAsync('sw_vers -productVersion', { encoding: 'utf8' });
+        result.version = stdout.trim();
+    } catch (e) {
+        // 실패 시 무시
+    }
+
+    return result;
+}
+
 /**
  * 특정 명령어의 실행 파일 경로를 찾습니다.
  * @param {string} command - 찾을 명령어 이름
@@ -166,26 +256,161 @@ export async function getSystemInfoString(options = {}) {
     return lines.join('\n');
 }
 
+/**
+ * 명령어별 설치 방법을 반환합니다.
+ * @param {string} command - 명령어 이름
+ * @param {string} os - OS 타입
+ * @param {Object} linuxDistro - Linux 배포판 정보
+ * @returns {Object} { primary, alternatives, url }
+ */
+function getInstallInstructions(command, os, linuxDistro = null) {
+    const instructions = {
+        ripgrep: {
+            macos: {
+                primary: 'brew install ripgrep',
+                alternatives: ['cargo install ripgrep'],
+                url: 'https://github.com/BurntSushi/ripgrep#installation'
+            },
+            linux: {
+                apt: { primary: 'sudo apt install ripgrep', alternatives: [] },
+                dnf: { primary: 'sudo dnf install ripgrep', alternatives: [] },
+                yum: { primary: 'sudo yum install ripgrep', alternatives: [] },
+                pacman: { primary: 'sudo pacman -S ripgrep', alternatives: [] },
+                zypper: { primary: 'sudo zypper install ripgrep', alternatives: [] },
+                apk: { primary: 'sudo apk add ripgrep', alternatives: [] },
+                brew: { primary: 'brew install ripgrep', alternatives: [] },
+                default: { primary: 'cargo install ripgrep', alternatives: ['brew install ripgrep'] },
+                url: 'https://github.com/BurntSushi/ripgrep#installation'
+            }
+        },
+        node: {
+            macos: {
+                primary: 'brew install node',
+                alternatives: ['Use nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash'],
+                url: 'https://nodejs.org/'
+            },
+            linux: {
+                apt: { primary: 'sudo apt install nodejs npm', alternatives: ['curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt install -y nodejs'] },
+                dnf: { primary: 'sudo dnf install nodejs npm', alternatives: [] },
+                yum: { primary: 'sudo yum install nodejs npm', alternatives: [] },
+                pacman: { primary: 'sudo pacman -S nodejs npm', alternatives: [] },
+                zypper: { primary: 'sudo zypper install nodejs npm', alternatives: [] },
+                apk: { primary: 'sudo apk add nodejs npm', alternatives: [] },
+                brew: { primary: 'brew install node', alternatives: [] },
+                default: { primary: 'Use nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash', alternatives: [] },
+                url: 'https://nodejs.org/'
+            }
+        },
+        bash: {
+            macos: {
+                primary: 'bash is built-in on macOS',
+                alternatives: [],
+                url: null
+            },
+            linux: {
+                apt: { primary: 'sudo apt install bash', alternatives: [] },
+                dnf: { primary: 'sudo dnf install bash', alternatives: [] },
+                yum: { primary: 'sudo yum install bash', alternatives: [] },
+                pacman: { primary: 'sudo pacman -S bash', alternatives: [] },
+                zypper: { primary: 'sudo zypper install bash', alternatives: [] },
+                apk: { primary: 'sudo apk add bash', alternatives: [] },
+                default: { primary: 'Install bash via your package manager', alternatives: [] },
+                url: null
+            }
+        },
+        python: {
+            macos: {
+                primary: 'brew install python3',
+                alternatives: [],
+                url: 'https://www.python.org/downloads/'
+            },
+            linux: {
+                apt: { primary: 'sudo apt install python3', alternatives: [] },
+                dnf: { primary: 'sudo dnf install python3', alternatives: [] },
+                yum: { primary: 'sudo yum install python3', alternatives: [] },
+                pacman: { primary: 'sudo pacman -S python', alternatives: [] },
+                zypper: { primary: 'sudo zypper install python3', alternatives: [] },
+                apk: { primary: 'sudo apk add python3', alternatives: [] },
+                brew: { primary: 'brew install python3', alternatives: [] },
+                default: { primary: 'Install python3 via your package manager', alternatives: [] },
+                url: 'https://www.python.org/downloads/'
+            }
+        }
+    };
+
+    const cmdInstructions = instructions[command];
+    if (!cmdInstructions) {
+        return { primary: `Install ${command}`, alternatives: [], url: null };
+    }
+
+    if (os === 'macos') {
+        return cmdInstructions.macos;
+    }
+
+    if (os === 'linux' && linuxDistro) {
+        const pm = linuxDistro.packageManager;
+        const linuxInst = cmdInstructions.linux;
+
+        if (pm && linuxInst[pm]) {
+            return {
+                ...linuxInst[pm],
+                url: linuxInst.url
+            };
+        }
+
+        return {
+            ...linuxInst.default,
+            url: linuxInst.url
+        };
+    }
+
+    return { primary: `Install ${command}`, alternatives: [], url: null };
+}
+
 /**
  * 필수 의존성을 체크하고 문제가 있으면 설치 방법을 안내합니다.
  * @param {Object} options - 옵션
  * @param {boolean} options.skipPython - Python 체크를 생략할지 여부
- * @returns {Promise<Object>} { success: boolean, issues: Array, os: string }
+ * @returns {Promise<Object>} { success: boolean, issues: Array, os: string, osInfo: Object }
  */
 export async function checkDependencies(options = {}) {
     const { skipPython = false } = options;
     const info = await getSystemInfo({ skipPython });
     const issues = [];
 
+    // OS 상세 정보 수집
+    let osInfo = { name: info.os, version: '' };
+    let linuxDistro = null;
+
+    if (info.os === 'linux') {
+        linuxDistro = await detectLinuxDistro();
+        osInfo = {
+            name: linuxDistro.name,
+            version: linuxDistro.version,
+            id: linuxDistro.id,
+            packageManager: linuxDistro.packageManager,
+            packageManagerName: linuxDistro.packageManagerName
+        };
+    } else if (info.os === 'macos') {
+        const macInfo = await getMacOSInfo();
+        osInfo = macInfo;
+    }
+
     // Windows 체크
     if (info.os === 'windows') {
         return {
             success: false,
             os: 'windows',
+            osInfo: { name: 'Windows', version: '' },
             issues: [{
                 type: 'unsupported_os',
                 message: 'Windows is not supported',
-                details: 'This application only supports macOS and Linux operating systems.'
+                details: 'This application requires macOS or Linux.',
+                suggestions: [
+                    'Use Windows Subsystem for Linux (WSL2)',
+                    'Use a Linux virtual machine',
+                    'Use Docker with a Linux container'
+                ]
             }],
             warnings: []
         };
@@ -193,33 +418,27 @@ export async function checkDependencies(options = {}) {
 
     // ripgrep 체크 (필수)
     if (!info.commands.hasRipgrep) {
-        const installInstructions = info.os === 'macos'
-            ? 'brew install ripgrep'
-            : info.os === 'linux'
-                ? 'apt install ripgrep  # or  brew install ripgrep  # or  cargo install ripgrep'
-                : 'Visit https://github.com/BurntSushi/ripgrep#installation';
-
+        const inst = getInstallInstructions('ripgrep', info.os, linuxDistro);
         issues.push({
             type: 'missing_command',
-            command: 'ripgrep (rg)',
-            message: 'ripgrep is not installed',
-            install: installInstructions
+            command: 'ripgrep',
+            displayName: 'ripgrep (rg)',
+            description: 'Fast regex-based code search tool',
+            message: 'ripgrep is required for code search functionality',
+            install: inst
         });
     }
 
-    // node 체크 (필수)
+    // node 체크 (필수) - 이 메시지를 보려면 node가 있어야 하지만 완전성을 위해 유지
     if (!info.commands.hasNode) {
-        const installInstructions = info.os === 'macos'
-            ? 'brew install node'
-            : info.os === 'linux'
-                ? 'Visit https://nodejs.org/ or use nvm: https://github.com/nvm-sh/nvm'
-                : 'Visit https://nodejs.org/';
-
+        const inst = getInstallInstructions('node', info.os, linuxDistro);
         issues.push({
             type: 'missing_command',
             command: 'node',
-            message: 'Node.js is not installed',
-            install: installInstructions
+            displayName: 'Node.js',
+            description: 'JavaScript runtime environment',
+            message: 'Node.js is required to run this application',
+            install: inst
         });
     }
 
@@ -227,42 +446,37 @@ export async function checkDependencies(options = {}) {
     if (!info.commands.hasBash) {
         const shellPath = await getCommandPath('sh');
         if (!shellPath) {
-            const installInstructions = info.os === 'macos'
-                ? 'bash is built-in on macOS. Please check your system.'
-                : info.os === 'linux'
-                    ? 'apt install bash  # or check your package manager'
-                    : 'bash or sh shell is required';
-
+            const inst = getInstallInstructions('bash', info.os, linuxDistro);
             issues.push({
                 type: 'missing_command',
-                command: 'bash or sh',
-                message: 'No compatible shell found',
-                install: installInstructions
+                command: 'bash',
+                displayName: 'Bash Shell',
+                description: 'Unix shell for command execution',
+                message: 'A compatible shell (bash or sh) is required',
+                install: inst
             });
         }
     }
 
-    // python 체크 (선택사항 - 경고만 표시, skipPython이 true면 생략)
+    // python 체크 (선택사항)
     const warnings = [];
     if (!skipPython && !info.commands.hasPython) {
-        const installInstructions = info.os === 'macos'
-            ? 'brew install python3'
-            : info.os === 'linux'
-                ? 'apt install python3  # or  yum install python3'
-                : 'Visit https://www.python.org/downloads/';
-
+        const inst = getInstallInstructions('python', info.os, linuxDistro);
         warnings.push({
             type: 'optional_command',
-            command: 'python or python3',
-            message: 'Python is not installed',
-            install: installInstructions,
-            impact: 'The following tools will be disabled: fetch_web_page, run_python_code'
+            command: 'python',
+            displayName: 'Python 3',
+            description: 'Programming language for web scraping and scripting',
+            message: 'Python is optional but enables additional features',
+            install: inst,
+            disabledFeatures: ['fetch_web_page', 'run_python_code']
         });
     }
 
     return {
         success: issues.length === 0,
         os: info.os,
+        osInfo,
         issues,
         warnings
     };