companionbot 0.6.0 → 0.8.0

package/README.md

@@ -29,12 +29,21 @@
 - **일회성 예약** - "내일 오전 9시에 알려줘"
 - **반복 작업** - "30분마다 주식 가격 확인해줘"
 
-### 🤖 고급 기능 (v0.3.0)
+### 🤖 고급 기능 (v0.3.0+)
 - **서브 에이전트** - 복잡한 작업을 백그라운드에서 처리
 - **백그라운드 실행** - 긴 명령어를 백그라운드에서 실행하고 결과 확인
 - **파일 시스템** - 워크스페이스 내 파일 읽기/쓰기/편집
 - **일일 메모리** - 대화 내용 자동 저장
 
+### 🧠 시맨틱 메모리 (v0.6.0)
+- **벡터 검색** - 임베딩 기반 관련 메모리 검색
+- **자동 인덱싱** - 메모리 파일 자동 청크 분할 및 임베딩
+- **유사도 매칭** - 의미 기반으로 관련 대화 기록 찾기
+
+### 🔧 시스템 (v0.6.0)
+- **헬스 체크** - 봇 상태 모니터링 (uptime, 메시지 수, 오류 수)
+- **업데이트 알림** - 새 버전 출시 시 자동 알림
+
 ## 설치
 
 ### 사전 준비
@@ -273,7 +282,22 @@ npm test       # 테스트 실행
 
 ## 버전 히스토리
 
-### v0.3.0 (현재)
+### v0.6.0 (현재)
+- 🧠 시맨틱 메모리 검색 (임베딩 기반)
+- 💚 헬스 체크 모니터링
+- 🔄 자동 업데이트 알림
+
+### v0.5.0
+- 🔒 보안 강화 (SSRF 방지, 경로 검증)
+- ✅ 테스트 추가 (vitest)
+- 📖 문서 개선
+
+### v0.4.0
+- 🛡️ 보안 강화 (TOCTOU, 심볼릭 링크 검증)
+- 🧹 세션 자동 정리
+- 🔧 환경변수 기반 경로 설정
+
+### v0.3.0
 - 🔍 웹 검색 (Brave Search API)
 - 🕐 Cron 스케줄링 (한국어 지원)
 - 🤖 서브 에이전트 (백그라운드 작업)

package/dist/ai/claude.js

@@ -1,5 +1,48 @@
-import Anthropic from "@anthropic-ai/sdk";
+import Anthropic, { APIError } from "@anthropic-ai/sdk";
 import { tools, executeTool } from "../tools/index.js";
+import { sleep } from "../utils/time.js";
+import { MAX_RETRIES, BASE_RETRY_DELAY_MS } from "../utils/constants.js";
+async function withRetry(fn, retries = MAX_RETRIES) {
+    let lastError = null;
+    for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // APIError 타입 체크
+            if (error instanceof APIError) {
+                lastError = error;
+                // Rate limit (429)
+                if (error.status === 429) {
+                    const retryAfter = error.headers?.["retry-after"];
+                    const delay = retryAfter
+                        ? parseInt(retryAfter) * 1000
+                        : BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+                    console.log(`[RateLimit] 429 received, waiting ${delay}ms (attempt ${attempt + 1}/${retries})`);
+                    await sleep(delay);
+                    continue;
+                }
+                // 서버 에러 (500+)
+                if (error.status >= 500) {
+                    const delay = BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+                    console.log(`[ServerError] ${error.status}, waiting ${delay}ms (attempt ${attempt + 1}/${retries})`);
+                    await sleep(delay);
+                    continue;
+                }
+            }
+            // 일반 Error 처리
+            if (error instanceof Error) {
+                lastError = error;
+            }
+            else {
+                lastError = new Error(String(error));
+            }
+            // 다른 에러는 바로 throw
+            throw error;
+        }
+    }
+    throw lastError;
+}
 let anthropic = null;
 function getClient() {
     if (!anthropic) {
@@ -58,20 +101,7 @@ export async function chat(messages, systemPrompt, modelId = "sonnet") {
         return params;
     };
     let response;
-    try {
-        response = await client.messages.create(buildRequestParams());
-    }
-    catch (error) {
-        if (error instanceof Anthropic.APIError) {
-            if (error.status === 429) {
-                throw new Error("API 요청이 너무 많아. 잠시 후 다시 시도해줘.");
-            }
-            if (error.status >= 500) {
-                throw new Error("AI 서버에 문제가 생겼어. 잠시 후 다시 시도해줘.");
-            }
-        }
-        throw error;
-    }
+    response = await withRetry(() => client.messages.create(buildRequestParams()));
     // Tool use 루프 - Claude가 도구 사용을 멈출 때까지 반복 (최대 10회)
     const MAX_TOOL_ITERATIONS = 10;
     let iterations = 0;
@@ -103,20 +133,7 @@ export async function chat(messages, systemPrompt, modelId = "sonnet") {
             content: toolResults,
         });
         // 다음 응답 요청 (도구 루프에서도 thinking 유지)
-        try {
-            response = await client.messages.create(buildRequestParams());
-        }
-        catch (error) {
-            if (error instanceof Anthropic.APIError) {
-                if (error.status === 429) {
-                    throw new Error("API 요청이 너무 많아. 잠시 후 다시 시도해줘.");
-                }
-                if (error.status >= 500) {
-                    throw new Error("AI 서버에 문제가 생겼어. 잠시 후 다시 시도해줘.");
-                }
-            }
-            throw error;
-        }
+        response = await withRetry(() => client.messages.create(buildRequestParams()));
     }
     // 반복 횟수 초과 시 경고
     if (iterations >= MAX_TOOL_ITERATIONS) {
@@ -163,7 +180,9 @@ export async function chatSmart(messages, systemPrompt, modelId, onChunk) {
     // (도구 호출 폴백 시 chat()에서 thinking 사용됨)
     let accumulated = "";
     let stopReason = null;
-    try {
+    // 스트리밍에 withRetry 적용 - 실패 시 자동 재시도
+    return await withRetry(async () => {
+        accumulated = ""; // 재시도 시 초기화
         const stream = client.messages.stream(params);
         // 스트리밍 이벤트 처리
         stream.on("text", async (text) => {
@@ -187,30 +206,5 @@ export async function chatSmart(messages, systemPrompt, modelId, onChunk) {
         }
         // 성공적으로 스트리밍 완료
         return { text: accumulated, usedTools: false };
-    }
-    catch (error) {
-        // 스트리밍 에러 핸들링
-        if (error instanceof Anthropic.APIError) {
-            if (error.status === 429) {
-                throw new Error("API 요청이 너무 많아. 잠시 후 다시 시도해줘.");
-            }
-            if (error.status >= 500) {
-                throw new Error("AI 서버에 문제가 생겼어. 잠시 후 다시 시도해줘.");
-            }
-        }
-        // 연결 끊김 등 스트리밍 에러 - 이미 받은 내용이 있으면 반환 시도
-        if (accumulated.length > 50) {
-            console.warn("[Stream] Connection error, returning partial response");
-            return { text: accumulated + "\n\n(연결이 끊겨서 응답이 잘렸을 수 있어)", usedTools: false };
-        }
-        // 응답이 거의 없으면 일반 chat으로 재시도
-        console.warn("[Stream] Connection error, retrying with chat()");
-        try {
-            const text = await chat(messages, systemPrompt, modelId);
-            return { text, usedTools: false };
-        }
-        catch (retryError) {
-            throw retryError;
-        }
-    }
+    });
 }

package/dist/calendar/index.js

@@ -1,4 +1,5 @@
-import { google } from "googleapis";
+import { calendar } from "@googleapis/calendar";
+import { OAuth2Client } from "google-auth-library";
 import * as fs from "fs/promises";
 import * as path from "path";
 import * as http from "http";
@@ -69,7 +70,7 @@ export async function getAuthUrl() {
     const creds = await loadCredentials();
     if (!creds)
         return null;
-    const oauth2Client = new google.auth.OAuth2(creds.client_id, creds.client_secret, REDIRECT_URI);
+    const oauth2Client = new OAuth2Client(creds.client_id, creds.client_secret, REDIRECT_URI);
     return oauth2Client.generateAuthUrl({
         access_type: "offline",
         scope: SCOPES,
@@ -120,7 +121,7 @@ export async function exchangeCodeForToken(code) {
     const creds = await loadCredentials();
     if (!creds)
         return false;
-    const oauth2Client = new google.auth.OAuth2(creds.client_id, creds.client_secret, REDIRECT_URI);
+    const oauth2Client = new OAuth2Client(creds.client_id, creds.client_secret, REDIRECT_URI);
     try {
         const { tokens } = await oauth2Client.getToken(code);
         if (tokens.access_token && tokens.refresh_token) {
@@ -145,7 +146,7 @@ async function getAuthClient() {
     if (!creds || !token) {
         throw new Error("Calendar not configured. Use /calendar_setup");
     }
-    const oauth2Client = new google.auth.OAuth2(creds.client_id, creds.client_secret, REDIRECT_URI);
+    const oauth2Client = new OAuth2Client(creds.client_id, creds.client_secret, REDIRECT_URI);
     oauth2Client.setCredentials({
         access_token: token.access_token,
         refresh_token: token.refresh_token,
@@ -169,17 +170,18 @@ async function getAuthClient() {
 // 캘린더 API 인스턴스
 async function getCalendar() {
     const auth = await getAuthClient();
-    return google.calendar({ version: "v3", auth });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return calendar({ version: "v3", auth: auth });
 }
 // 오늘 일정 조회
 export async function getTodayEvents() {
-    const calendar = await getCalendar();
+    const cal = await getCalendar();
     const now = new Date();
     const startOfDay = new Date(now);
     startOfDay.setHours(0, 0, 0, 0);
     const endOfDay = new Date(now);
     endOfDay.setHours(23, 59, 59, 999);
-    const response = await calendar.events.list({
+    const response = await cal.events.list({
         calendarId: "primary",
         timeMin: startOfDay.toISOString(),
         timeMax: endOfDay.toISOString(),
@@ -190,8 +192,8 @@ export async function getTodayEvents() {
 }
 // 특정 기간 일정 조회
 export async function getEvents(startDate, endDate) {
-    const calendar = await getCalendar();
-    const response = await calendar.events.list({
+    const cal = await getCalendar();
+    const response = await cal.events.list({
         calendarId: "primary",
         timeMin: startDate.toISOString(),
         timeMax: endDate.toISOString(),
@@ -203,7 +205,7 @@ export async function getEvents(startDate, endDate) {
 }
 // 일정 추가
 export async function addEvent(summary, startTime, endTime, description) {
-    const calendar = await getCalendar();
+    const cal = await getCalendar();
     // 종료 시간이 없으면 1시간 후
     const end = endTime || new Date(startTime.getTime() + 60 * 60 * 1000);
     const event = {
@@ -218,7 +220,7 @@ export async function addEvent(summary, startTime, endTime, description) {
             timeZone: "Asia/Seoul",
         },
     };
-    const response = await calendar.events.insert({
+    const response = await cal.events.insert({
         calendarId: "primary",
         requestBody: event,
     });
@@ -227,8 +229,8 @@ export async function addEvent(summary, startTime, endTime, description) {
 // 일정 삭제
 export async function deleteEvent(eventId) {
     try {
-        const calendar = await getCalendar();
-        await calendar.events.delete({
+        const cal = await getCalendar();
+        await cal.events.delete({
             calendarId: "primary",
             eventId,
         });

package/dist/cli/main.js

@@ -1,4 +1,5 @@
 import * as readline from "readline";
+import { checkbox, Separator } from "@inquirer/prompts";
 import { getSecret, setSecret } from "../config/secrets.js";
 import { isWorkspaceInitialized, initWorkspace, getWorkspacePath, } from "../workspace/index.js";
 import { createBot } from "../telegram/bot.js";
@@ -20,51 +21,167 @@ async function question(rl, prompt) {
 }
 async function interactiveSetup() {
     const rl = createPrompt();
-    console.log("\n🤖 CompanionBot 첫 실행입니다!\n");
+    console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║             🤖 CompanionBot 첫 실행 가이드                    ║
+╚═══════════════════════════════════════════════════════════════╝
+
+CompanionBot은 Telegram에서 동작하는 개인 AI 비서예요.
+
+💡 언제든지 'q'를 입력하면 설정을 취소할 수 있어요.
+`);
     try {
+        // ===== STEP 1: 기능 선택 =====
+        console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[STEP 1] 사용할 기능 선택
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌──────────────────────────────────────────────────────────────┐
+│  [필수] 기본 기능 (자동 포함)                                │
+│  ├─ 💬 AI 대화         자연스러운 한국어 대화               │
+│  ├─ 📁 파일 관리       문서/코드 읽기·쓰기                  │
+│  ├─ ⏰ 리마인더        알림 설정 ("3시에 알려줘")           │
+│  └─ 🧠 메모리          대화 기억, 장기 기억 저장            │
+└──────────────────────────────────────────────────────────────┘
+`);
+        const features = {
+            webSearch: false,
+            calendar: false,
+            weather: false,
+        };
+        let selectedValues = [];
+        try {
+            selectedValues = await checkbox({
+                message: "추가 기능 선택 (Space=선택, Enter=확정)",
+                choices: [
+                    { name: "🔍 웹 검색 - Brave API, 무료 2000/월", value: "webSearch" },
+                    { name: "📅 캘린더 - Google Calendar 연동", value: "calendar" },
+                    { name: "🌤️  날씨 - OpenWeatherMap, 무료", value: "weather" },
+                    new Separator("  ● 다음 단계로"),
+                ],
+            });
+        }
+        catch {
+            console.log("\n👋 설정을 취소했습니다.");
+            rl.close();
+            return false;
+        }
+        features.webSearch = selectedValues.includes("webSearch");
+        features.calendar = selectedValues.includes("calendar");
+        features.weather = selectedValues.includes("weather");
+        // 선택 요약
+        const selectedFeatures = [];
+        if (features.webSearch)
+            selectedFeatures.push("🔍 웹 검색");
+        if (features.calendar)
+            selectedFeatures.push("📅 캘린더");
+        if (features.weather)
+            selectedFeatures.push("🌤️ 날씨");
+        console.log(`
+   ✓ 선택됨: ${selectedFeatures.length > 0 ? selectedFeatures.join(", ") : "기본 기능만"}
+`);
+        // ===== STEP 2: 필수 API 키 =====
+        console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[STEP 2] 필수 API 키 입력
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
         // Telegram Bot Token
-        console.log("[1/2] Telegram Bot Token");
-        console.log("      @BotFather에서 봇 생성 후 토큰을 붙여넣으세요.");
-        console.log("      (https://t.me/BotFather)\n");
+        console.log(`   📱 Telegram Bot Token
+   
+      1. Telegram에서 @BotFather 검색
+      2. /newbot → 이름 입력 → 유저네임 입력 (_bot으로 끝나야 함)
+      3. 토큰 복사 (예: 123456:ABC-DEF...)
+      🔗 https://t.me/BotFather
+`);
         const token = await question(rl, "      Token: ");
-        if (!token) {
-            console.log("\n❌ 토큰이 필요합니다.");
+        if (!token || token.toLowerCase() === "q") {
+            console.log("\n👋 설정을 취소했습니다.");
             rl.close();
             return false;
         }
         await setSecret("telegram-token", token);
         console.log("      ✓ 저장됨\n");
         // Anthropic API Key
-        console.log("[2/2] Anthropic API Key");
-        console.log("      console.anthropic.com에서 발급받으세요.");
-        console.log("      (https://console.anthropic.com/settings/keys)\n");
+        console.log(`   🧠 Anthropic API Key
+   
+      1. https://console.anthropic.com 접속 (회원가입/로그인)
+      2. Settings > API Keys > Create Key
+      3. 키 복사 (sk-ant-...)
+      🔗 https://console.anthropic.com/settings/keys
+`);
         const apiKey = await question(rl, "      API Key: ");
-        if (!apiKey) {
-            console.log("\n❌ API 키가 필요합니다.");
+        if (!apiKey || apiKey.toLowerCase() === "q") {
+            console.log("\n👋 설정을 취소했습니다. (Telegram 토큰은 저장됨)");
             rl.close();
             return false;
         }
         await setSecret("anthropic-api-key", apiKey);
         console.log("      ✓ 저장됨\n");
-        // 선택적 기능 설정
-        const setupOptional = await question(rl, "[선택] 추가 기능을 설정하시겠습니까? (y/n): ");
-        if (setupOptional.toLowerCase() === "y") {
-            console.log("");
-            // 날씨 기능
-            const useWeather = await question(rl, "      날씨 기능을 사용하시겠습니까? (y/n): ");
-            if (useWeather.toLowerCase() === "y") {
-                console.log("\n      OpenWeatherMap API Key가 필요합니다.");
-                console.log("      (https://openweathermap.org)\n");
-                const weatherKey = await question(rl, "      API Key: ");
+        // ===== STEP 3: 선택 API 키 =====
+        if (features.webSearch || features.calendar || features.weather) {
+            console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[STEP 3] 선택한 기능 API 키 입력
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Enter를 누르면 해당 기능을 건너뛸 수 있어요.
+`);
+            // 웹 검색 API
+            if (features.webSearch) {
+                console.log(`   🔍 Brave Search API (무료 2000회/월)
+   
+      1. https://brave.com/search/api 접속
+      2. Get Started > 가입 > API 키 생성
+`);
+                const braveKey = await question(rl, "      API Key (Enter=건너뛰기, q=취소): ");
+                if (braveKey.toLowerCase() === "q") {
+                    console.log("\n👋 설정을 취소했습니다.");
+                    rl.close();
+                    return false;
+                }
+                if (braveKey) {
+                    await setSecret("brave-api-key", braveKey);
+                    console.log("      ✓ 저장됨\n");
+                }
+                else {
+                    console.log("      → 건너뜀 (나중에: companionbot setup brave <KEY>)\n");
+                }
+            }
+            // 날씨 API
+            if (features.weather) {
+                console.log(`   🌤️  OpenWeatherMap API (무료)
+   
+      1. https://openweathermap.org 접속 > Sign Up
+      2. API Keys 메뉴에서 키 확인/생성
+`);
+                const weatherKey = await question(rl, "      API Key (Enter=건너뛰기, q=취소): ");
+                if (weatherKey.toLowerCase() === "q") {
+                    console.log("\n👋 설정을 취소했습니다.");
+                    rl.close();
+                    return false;
+                }
                 if (weatherKey) {
                     await setSecret("openweathermap-api-key", weatherKey);
                     console.log("      ✓ 저장됨\n");
                 }
                 else {
-                    console.log("      → 건너뜀\n");
+                    console.log("      → 건너뜀 (나중에: companionbot setup weather <KEY>)\n");
                 }
             }
+            // 캘린더
+            if (features.calendar) {
+                console.log(`   📅 Google Calendar
+   
+      캘린더는 봇 실행 후 /calendar_setup 명령어로 설정합니다.
+      (OAuth 인증이 필요해서 브라우저가 열려요)
+`);
+                await question(rl, "      Enter를 눌러 계속...");
+                console.log("");
+            }
         }
+        console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ 설정 완료!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
         rl.close();
         return true;
     }
@@ -93,15 +210,35 @@ async function main() {
     }
     // 3. 워크스페이스 초기화
     const workspaceReady = await isWorkspaceInitialized();
+    const workspacePath = getWorkspacePath();
     if (!workspaceReady) {
-        console.log("📁 워크스페이스 생성 중...");
+        console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                    📁 워크스페이스 생성                        ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
         await initWorkspace();
-        console.log(`   → ${getWorkspacePath()} 생성 완료\n`);
+        console.log(`   경로: ${workspacePath}
+   
+   생성된 파일들:
+   ├── IDENTITY.md   ← 봇의 이름과 성격 설정
+   ├── SOUL.md       ← 봇의 행동 원칙
+   ├── USER.md       ← 당신에 대한 정보 (봇이 참고)
+   ├── AGENTS.md     ← 봇 행동 가이드
+   ├── MEMORY.md     ← 장기 기억 저장소
+   └── memory/       ← 일일 메모리 폴더
+
+   💡 팁: IDENTITY.md와 USER.md를 편집해서 봇을 커스터마이즈하세요!
+`);
     }
     // 4. 환경변수 설정
     process.env.ANTHROPIC_API_KEY = apiKey;
     // 5. 봇 시작
-    console.log("🚀 봇을 시작합니다!\n");
+    console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                      🚀 봇 시작!                              ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
     const bot = createBot(token);
     // Graceful shutdown
     async function shutdown() {
@@ -117,8 +254,22 @@ async function main() {
     process.once("SIGTERM", () => void shutdown());
     bot.start({
         onStart: (botInfo) => {
-            console.log(`✓ @${botInfo.username} 시작됨`);
-            console.log(`  텔레그램에서 대화를 시작하세요!\n`);
+            console.log(`   ✓ @${botInfo.username} 연결됨!
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   이제 Telegram에서 @${botInfo.username} 검색해서 대화해보세요!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   📱 명령어 목록:
+   /help       - 도움말
+   /model      - AI 모델 변경 (haiku/sonnet/opus)
+   /compact    - 대화 요약 (토큰 절약)
+   /health     - 봇 상태 확인
+   /calendar   - 캘린더 연동 (Google)
+
+   ⌨️  Ctrl+C로 종료
+   📂 워크스페이스: ${workspacePath}
+`);
         },
     });
 }

package/dist/cron/parser.js

@@ -131,50 +131,82 @@ export function parseCronExpression(expr) {
 }
 /**
  * Calculate the next run time for a cron expression
+ * Returns null if no valid next run time is found (safer than throwing)
  */
 export function getNextCronRun(expression, fromDate = new Date(), timezone) {
-    const parsed = parseCronExpression(expression);
-    const from = new Date(fromDate);
-    // Start from the next minute
-    from.setSeconds(0);
-    from.setMilliseconds(0);
-    from.setMinutes(from.getMinutes() + 1);
-    // Search for the next matching time (max 2 years ahead)
-    const maxIterations = 365 * 24 * 60 * 2; // 2 years in minutes
-    for (let i = 0; i < maxIterations; i++) {
-        const candidate = new Date(from.getTime() + i * 60000);
-        const minute = candidate.getMinutes();
-        const hour = candidate.getHours();
-        const dayOfMonth = candidate.getDate();
-        const month = candidate.getMonth() + 1;
-        const dayOfWeek = candidate.getDay();
-        if (parsed.minute.values.includes(minute) &&
-            parsed.hour.values.includes(hour) &&
-            parsed.month.values.includes(month) &&
-            (parsed.dayOfMonth.values.includes(dayOfMonth) ||
-                parsed.dayOfWeek.values.includes(dayOfWeek))) {
-            return candidate;
+    // null/undefined/빈 문자열 처리
+    if (!expression || expression.trim() === "") {
+        console.warn("[Cron] Empty cron expression provided");
+        return null;
+    }
+    try {
+        const parsed = parseCronExpression(expression);
+        const from = new Date(fromDate);
+        // Invalid date 체크
+        if (isNaN(from.getTime())) {
+            console.warn("[Cron] Invalid fromDate provided");
+            return null;
+        }
+        // Start from the next minute
+        from.setSeconds(0);
+        from.setMilliseconds(0);
+        from.setMinutes(from.getMinutes() + 1);
+        // Search for the next matching time (max 2 years ahead)
+        const maxIterations = 365 * 24 * 60 * 2; // 2 years in minutes
+        for (let i = 0; i < maxIterations; i++) {
+            const candidate = new Date(from.getTime() + i * 60000);
+            const minute = candidate.getMinutes();
+            const hour = candidate.getHours();
+            const dayOfMonth = candidate.getDate();
+            const month = candidate.getMonth() + 1;
+            const dayOfWeek = candidate.getDay();
+            if (parsed.minute.values.includes(minute) &&
+                parsed.hour.values.includes(hour) &&
+                parsed.month.values.includes(month) &&
+                (parsed.dayOfMonth.values.includes(dayOfMonth) ||
+                    parsed.dayOfWeek.values.includes(dayOfWeek))) {
+                return candidate;
+            }
         }
+        console.warn(`[Cron] Could not find next run time for: ${expression}`);
+        return null;
+    }
+    catch (error) {
+        console.error(`[Cron] Error parsing expression "${expression}":`, error);
+        return null;
     }
-    throw new Error(`Could not find next run time for: ${expression}`);
 }
 /**
  * Get the next run time for any schedule type
+ * Returns NaN if schedule is invalid (check with isNaN())
  */
 export function getNextRun(schedule, now = new Date()) {
+    // null/undefined 처리
+    if (!schedule) {
+        console.warn("[Cron] No schedule provided to getNextRun");
+        return NaN;
+    }
     switch (schedule.kind) {
         case "at":
-            return schedule.atMs;
+            return schedule.atMs ?? NaN;
         case "every": {
+            const everyMs = schedule.everyMs || schedule.intervalMs;
+            if (!everyMs || everyMs <= 0) {
+                console.warn("[Cron] Invalid everyMs in schedule");
+                return NaN;
+            }
             const startMs = schedule.startMs ?? now.getTime();
             const elapsed = now.getTime() - startMs;
-            const intervals = Math.floor(elapsed / schedule.everyMs);
-            return startMs + (intervals + 1) * schedule.everyMs;
+            const intervals = Math.floor(elapsed / everyMs);
+            return startMs + (intervals + 1) * everyMs;
+        }
+        case "cron": {
+            const nextRun = getNextCronRun(schedule.expression, now, schedule.timezone);
+            return nextRun ? nextRun.getTime() : NaN;
         }
-        case "cron":
-            return getNextCronRun(schedule.expression, now, schedule.timezone).getTime();
         default:
-            throw new Error(`Unknown schedule kind: ${schedule.kind}`);
+            console.warn(`[Cron] Unknown schedule kind: ${schedule.kind}`);
+            return NaN;
     }
 }
 /**