saju8z 1.1.0 → 1.2.0

package/README.md

@@ -1,10 +1,10 @@
 # saju8z
 
-생년월일시로 사주팔자와 십성을 계산하는 만세력 CLI 라이브러리입니다. 
+생년월일시로 사주팔자와 십성을 계산하고, 시간을 모르면 삼주(년·월·일)를 제공하는 만세력 CLI 라이브러리입니다. 
 
 양력/음력/윤달을 지원하고, 결과를 텍스트/JSON/AI 전달용 프롬프트로 출력합니다.
 
-**Node.js 22 이상과 npm**이 필요합니다. 터미널에서 바로 사용하려면 `--date`, `--time`을 본인의 생년월일시로 바꾸세요.
+**Node.js 22 이상과 npm**이 필요합니다. 터미널에서 바로 사용하려면 `--date`·`--time` 또는 `--dt`를 본인의 생년월일시로 바꾸세요.
 
 
 
@@ -27,6 +27,132 @@ saju8z --date 2000-02-25 --time 04:10
 
 
 
+### 인자 없이 실행하고 날짜·시각 입력하기
+
+옵션 없이 `saju8z`를 실행하면 생년월일과 출생 시각을 차례로 질문합니다. 아래처럼 값을 입력한 뒤 각각 Enter를 누르세요.
+
+```sh
+saju8z
+```
+
+입력 예시:
+
+```text
+생년월일과 출생 시각을 입력하세요. 양력·현재 GMT 시차로 계산합니다.
+생년월일 (YYYY-MM-DD, 예: 1998-03-05): 1998-03-05
+출생 시각 (HH:mm, 예: 11:00 / 시간을 모르면 비워두고 Enter): 11:00
+
+[만세력]
+...
+```
+
+- 날짜는 `1998-03-05`처럼 연도 4자리·월 2자리·일 2자리를 하이픈으로 구분합니다.
+- 시각은 `11:00`처럼 24시간제의 시·분을 콜론으로 구분합니다. 오후 11시는 `23:00`, 자정은 `00:00`입니다.
+- 시간을 모르면 시각 질문에서 아무것도 적지 않고 Enter를 누르세요. 삼주만 출력합니다.
+- 시간을 입력하면 **양력·실행 환경의 현재 GMT 시차·기본 텍스트 형식**으로 사주를 출력합니다. 시간을 생략하면 양력 날짜 기준으로 계산하며 GMT 환산과 -30분 보정은 생략합니다.
+- 잘못된 날짜·시각이나 빈 날짜는 오류로 종료합니다. 빈 시각은 시간 미상으로 처리합니다. 다시 실행해 입력하세요. 음력·윤달·고정 시차·다른 출력 형식은 아래 CLI 옵션을 사용하세요.
+
+대화형 입력은 **인자가 전혀 없을 때만** 시작합니다. 옵션을 전달하면 `--date` 또는 `--dt`가 필요하며, `--time`은 선택입니다. 입력 안내는 표준 오류(stderr), 계산 결과는 표준 출력(stdout)에 기록합니다.
+
+### 날짜와 시각을 한 번에 입력하기
+
+`--dt`는 날짜만 적는 **`YYYYMMDD` 8자리**와 시각까지 적는 **`YYYYMMDDHHmm` 12자리**를 지원합니다. `19980305`는 `--date 1998-03-05`와 같으며 삼주를 출력합니다. `199803051100`은 `--date 1998-03-05 --time 11:00`과 같은 사주를 출력합니다.
+
+```sh
+saju8z --dt 19980305
+saju8z --dt 199803051100
+saju8z --dt 199803051100 --gmt +09:00 --format json
+saju8z --dt=199803051100 --gmt +09:00 --format prompt
+```
+
+**옵션으로 실행할 때는 `--date` 또는 `--dt`를 입력해야 합니다. `--time`은 선택입니다.** `--dt`와 `--date`·`--time`을 혼용하면 오류가 발생합니다. 월·일·시·분은 각각 두 자리로 입력하며, 날짜와 시각의 유효성 검사는 기존 입력 방식과 같습니다. 시간이 있으면 `--gmt` 생략 시 현재 시차를 사용합니다. 시간이 없으면 시차 환산을 생략합니다. `--calendar lunar`·`--leap`는 두 방식 모두 사용할 수 있습니다.
+
+### 시간을 모를 때 삼주 출력
+
+```sh
+saju8z --date 1998-03-05
+saju8z --dt 19980305
+```
+
+위 두 명령은 동일한 삼주 결과를 반환합니다.
+
+```text
+
+[만세력]
+양력 날짜: 1998-03-05
+출생 시각: 미상 (삼주만 제공하며 시주는 추정하거나 해석하지 않습니다.)
+시간 미상으로 GMT 환산과 -30분 보정은 적용하지 않았습니다.
+일간: 신금(辛金)
+
+년주: 무인(戊寅)
+- 천간: 무(戊), 토(土), 정인
+- 지지: 인(寅), 목(木), 정재
+
+월주: 갑인(甲寅)
+- 천간: 갑(甲), 목(木), 정재
+- 지지: 인(寅), 목(木), 정재
+
+일주: 신해(辛亥)
+- 천간: 신(辛), 금(金), 본원
+- 지지: 해(亥), 수(水), 상관
+```
+
+시각이 없으면 입력 날짜를 그대로 사용합니다. 음력 입력은 양력으로 변환한 날짜를 사용하며, GMT 환산과 -30분 보정은 적용하지 않습니다. 입춘·절입 당일부터 새 년주·월주를 적용합니다. 이 기준은 출생 시각을 추정한 결과가 아닙니다.
+
+```sh
+saju8z --dt 19980305 --format json
+```
+
+<details>
+<summary>시간 미상 JSON 결과 펼치기</summary>
+
+```json
+{
+  "normalizedDateTime": {
+    "year": 1998,
+    "month": 3,
+    "day": 5,
+    "hour": null,
+    "minute": null
+  },
+  "calculationDateTime": {
+    "year": 1998,
+    "month": 3,
+    "day": 5,
+    "hour": null,
+    "minute": null
+  },
+  "fourPillars": {
+    "year": {
+      "stem": "무",
+      "branch": "인"
+    },
+    "month": {
+      "stem": "갑",
+      "branch": "인"
+    },
+    "day": {
+      "stem": "신",
+      "branch": "해"
+    },
+    "hour": null
+  },
+  "tenGods": {
+    "yearStem": "정인",
+    "yearBranch": "정재",
+    "monthStem": "정재",
+    "monthBranch": "정재",
+    "dayBranch": "상관",
+    "hourStem": null,
+    "hourBranch": null
+  }
+}
+```
+
+</details>
+
+시간 미상 결과는 `fourPillars.hour`, `tenGods.hourStem`, `tenGods.hourBranch`가 `null`이며, `normalizedDateTime`·`calculationDateTime`의 `hour`·`minute`도 `null`입니다. 두 날짜 객체는 같은 양력 날짜를 담습니다. 텍스트·프롬프트에는 년주·월주·일주만 표시하고, 프롬프트에는 시주를 추정하거나 해석하지 않도록 안내합니다.
+
 ### 출력 형식 선택
 
 
@@ -50,6 +176,7 @@ saju8z --date 2000-02-25 --time 04:10
 &nbsp;
 
 ```text
+
 [만세력]
 양력 환산 시각: 2000-02-25 04:10 (GMT+09:00)
 -30분 보정 후 계산 시각: 2000-02-25 03:40
@@ -212,8 +339,9 @@ npx --yes saju8z --date 2017-05-01 --time 12:00 --gmt +09:00 --calendar lunar --
 
 | 옵션             | 필수  | 기본값·설명                                                |
 | -------------- | --- | ----------------------------------------------------- |
-| `--date`       | 예   | 생년월일 `YYYY-MM-DD`. 월·일은 두 자리                          |
-| `--time`       | 예   | 출생 시각 `HH:mm`, `00:00`\~`23:59`. 초는 지원하지 않음           |
+| `--dt`         | 선택 | 날짜 `YYYYMMDD` 8자리 또는 날짜·시각 `YYYYMMDDHHmm` 12자리 |
+| `--date`       | 조건부 | 생년월일 `YYYY-MM-DD`. 옵션 실행 시 `--dt`가 없으면 필수                          |
+| `--time`       | 아니요 | 출생 시각 `HH:mm`, `00:00`\~`23:59`. 생략하면 삼주 출력 |
 | `--gmt`        | 아니요 | 고정 시차 `±HH:mm`, `-12:00`\~`+14:00` 기본값은 실행 환경의 현재 GMT |
 | `--calendar`   | 아니요 | `solar`(기본, 양력) 또는 `lunar`(한국 음력)                     |
 | `--leap`       | 아니요 | 음력 윤달일 때 지정. `--calendar lunar`와 함께 사용                |
@@ -223,7 +351,7 @@ npx --yes saju8z --date 2017-05-01 --time 12:00 --gmt +09:00 --calendar lunar --
 
 시차는 `--gmt -05:00` 또는 `--gmt=-05:00`처럼 전달합니다.
 
-`--gmt`를 생략하면 출생일 당시가 아닌 **실행 시점의 GMT 시차**를 사용합니다. 한국 표준시 환경에서는 `+09:00`이며, 서머타임을 사용하는 환경에서는 현재 서머타임도 반영됩니다. 출생 당시 위치의 시차로 계산하려면 해당 시차를 직접 지정하세요.
+`--gmt`를 생략하면 출생일 당시가 아닌 **실행 시점의 GMT 시차**를 사용합니다. 한국 표준시 환경에서는 `+09:00`이며, 서머타임을 사용하는 환경에서는 현재 서머타임도 반영됩니다. 출생 당시 위치의 시차로 계산하려면 해당 시차를 직접 지정하세요. 시간 미상일 때는 `--gmt` 값에 관계없이 날짜 기준 삼주를 계산합니다. 전달한 GMT 값의 형식과 범위는 계속 검증합니다.
 
 
 
@@ -247,6 +375,17 @@ console.log(formatSajuChart(result, "prompt")); // AI 전달용 프롬프트 문
 
 
 
+시간을 모르면 라이브러리에서도 `time`을 생략하거나 `undefined`로 전달합니다.
+
+```ts
+const unknown = calculateSajuChart({ date: "1998-03-05", gmt: "+09:00" });
+console.log(unknown.fourPillars.hour); // null
+console.log(unknown.normalizedDateTime.hour); // null
+console.log(formatSajuChart(unknown)); // 년·월·일 삼주
+```
+
+시간을 명시한 호출은 `SajuChartResultWithTime`, 생략한 호출은 `SajuChartResultWithoutTime`으로 추론됩니다. `SajuChartResult`는 두 결과의 유니온입니다. `time`이 선택적인 `SajuChartInput` 변수를 전달하면 결과도 유니온이므로 시주를 사용하기 전에 `null`을 확인하세요. 두 결과 타입은 `saju8z`와 `saju8z/format`에서 가져올 수 있습니다. 저수준 `saju8z/core`의 기존 사주 타입과 함수는 그대로 사용합니다.
+
 ## 입력
 
 `calculateSajuChart(input)`은 다음 객체를 받습니다.
@@ -255,13 +394,13 @@ console.log(formatSajuChart(result, "prompt")); // AI 전달용 프롬프트 문
 | 필드          | 타입                   | 필수  | 설명                                         |
 | ----------- | -------------------- | --- | ------------------------------------------ |
 | `date`      | `string`             | 예   | `YYYY-MM-DD`. 선택한 달력 기준의 날짜                |
-| `time`      | `string`             | 예   | `HH:mm`, `00:00`\~`23:59`. 초는 지원하지 않음      |
+| `time`      | `string`             | 아니요 | `HH:mm`, `00:00`\~`23:59`. 생략 또는 `undefined`이면 시간 미상 |
 | `gmt`       | `string`             | 예   | 부호를 포함한 고정 시차 `±HH:mm`, `-12:00`\~`+14:00` |
 | `calendar`  | `"solar"`, `"lunar"` | 아니요 | 양력 또는 한국 음력. 기본값 `"solar"`                 |
 | `leapMonth` | `boolean`            | 아니요 | 음력 윤달 여부. 기본값 `false`, 음력에서만 `true` 허용     |
 
 
-라이브러리 API의 `gmt`는 출생 당시 날짜·시간의 시차를 직접 지정합니다. 예를 들어 한국 표준시는 `+09:00`, UTC는 `+00:00`입니다. 실행 환경의 시간대나 지역 이름으로 자동 추정하지 않습니다.
+라이브러리 API의 `gmt`는 출생 당시 날짜·시간의 시차를 직접 지정합니다. 예를 들어 한국 표준시는 `+09:00`, UTC는 `+00:00`입니다. 실행 환경의 시간대나 지역 이름으로 자동 추정하지 않습니다. `gmt`는 시간 미상 입력에서도 필수이며 형식을 검증하지만, 날짜 기준 계산에는 사용하지 않습니다. `time: ""`·`time: null`은 허용하지 않습니다. CLI에서도 `--time` 값을 비우는 대신 옵션을 생략하고, 대화형 질문에서만 빈 시각을 허용합니다.
 
 음력 윤달은 다음과 같이 입력합니다.
 
@@ -285,10 +424,10 @@ const result = calculateSajuChart({
 
 | 필드                    | 내용                                                                                                    |
 | --------------------- | ----------------------------------------------------------------------------------------------------- |
-| `normalizedDateTime`  | 양력으로 변환하고 GMT+09:00으로 환산한 `{ year, month, day, hour, minute }`                                        |
-| `calculationDateTime` | 환산 시각에 -30분 보정을 적용한 계산 시각                                                                             |
-| `fourPillars`         | `year`, `month`, `day`, `hour`의 사주팔자. 각 값은 `{ stem, branch }`                                         |
-| `tenGods`             | 일간 기준 십성. `yearStem`, `yearBranch`, `monthStem`, `monthBranch`, `dayBranch`, `hourStem`, `hourBranch` |
+| `normalizedDateTime`  | 시간이 있으면 GMT+09:00으로 환산한 양력 시각. 시간이 없으면 양력 날짜와 `hour: null`, `minute: null`                                        |
+| `calculationDateTime` | 시간이 있으면 -30분 보정한 시각. 시간이 없으면 `normalizedDateTime`과 동일한 날짜·null 시각                                                                             |
+| `fourPillars`         | `year`, `month`, `day`, `hour`의 사주팔자. 시간이 없으면 `hour: null`                                         |
+| `tenGods`             | 일간 기준 십성. `yearStem`, `yearBranch`, `monthStem`, `monthBranch`, `dayBranch`, `hourStem`, `hourBranch`. 시간 미상이면 마지막 두 필드는 `null` |
 
 
 천간·지지·십성은 `"병"`, `"진"`, `"식신"`과 같은 한국어 문자열입니다. 일간 자체의 십성 필드는 없으며, 만세력 텍스트에서는 `본원`으로 표시합니다.
@@ -312,13 +451,17 @@ const result = calculateSajuChart({
 
 ## 계산 기준과 지원 범위
 
+시간을 입력한 경우 기존 계산 기준을 적용합니다.
+
 1. 음력이면 양력으로 변환합니다.
 2. 입력 GMT에서 GMT+09:00으로 환산합니다.
 3. -30분을 보정한 시각으로 사주팔자를 계산합니다.
 
-년주는 입춘, 월주는 프로젝트의 고정 절입 시각 표, 일주는 자정을 기준으로 합니다. 고정 절입 표는 실제 연도별 천문 절기 시각과 차이가 있을 수 있습니다. 서머타임·역사적 시차·출생지 경도 보정은 자동 적용하지 않습니다.
+시간을 생략한 경우 음력 변환만 수행하고, 시차 환산과 -30분 보정 없이 해당 양력 날짜로 삼주를 계산합니다. 입춘·절입 당일부터 새 년주·월주를 적용하고 일주는 입력 날짜 기준입니다. 임의의 자정·정오를 출생 시각으로 대입하지 않습니다.
+
+시간을 입력한 경우 년주는 입춘, 월주는 프로젝트의 고정 절입 시각 표, 일주는 자정을 기준으로 합니다. 고정 절입 표는 실제 연도별 천문 절기 시각과 차이가 있을 수 있습니다. 서머타임·역사적 시차·출생지 경도 보정은 자동 적용하지 않습니다.
 
-양력 입력과 GMT+09:00 환산 날짜는 1900~2100년을 지원합니다. 음력은 1900년부터 음력 2050년 11월 18일까지의 유효 날짜를 지원합니다. -30분 보정으로 1900년 첫날이 전년 말로 이동할 수 있습니다.
+양력 입력과 GMT+09:00 환산 날짜는 1900~2100년을 지원합니다. 음력은 1900년부터 음력 2050년 11월 18일까지의 유효 날짜를 지원합니다. 시간을 입력하면 -30분 보정으로 1900년 첫날이 전년 말로 이동할 수 있습니다. 시간이 없으면 해당 날짜를 보존합니다.
 
 성별 입력은 필요하지 않습니다. 대운·세운·운세·성격 해석 기능은 제공하지 않습니다.
 

package/bin/saju8z.js

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
 import process from "node:process";
+import { createInterface } from "node:readline";
 import { calculateSajuChart, formatSajuChart, UserInputError } from "../dist/index.js";
 
-const HELP_TEXT = `사용법: saju8z --date YYYY-MM-DD --time HH:mm [--gmt ±HH:mm] [옵션]
+const HELP_TEXT = `사용법: saju8z
+        saju8z --date YYYY-MM-DD [--time HH:mm] [--gmt ±HH:mm] [옵션]
+        saju8z --dt YYYYMMDD[HHmm] [--gmt ±HH:mm] [옵션]
 
-필수 입력:
+인자 없이 실행하면 날짜와 시각을 차례로 입력받습니다.
+  날짜 예: 1998-03-05 / 시각 예: 11:00 (24시간제, 모르면 비워두고 Enter)
+  대화형 입력은 양력·현재 GMT 시차·text 출력을 사용합니다.
+
+옵션으로 실행할 때 필수 입력 (둘 중 하나):
+  --dt         생년월일 8자리 (YYYYMMDD) 또는 생년월일시 12자리 (YYYYMMDDHHmm)
   --date       생년월일 (YYYY-MM-DD)
-  --time       출생 시각 (HH:mm, 00:00~23:59)
+  --time       출생 시각 (선택, HH:mm, 00:00~23:59). 생략하면 삼주만 계산
+  --date 또는 --dt는 필수이며, --dt와 --date·--time은 혼용할 수 없습니다.
+  시간이 없으면 입력 날짜 기준으로 삼주를 계산하고 GMT 환산·-30분 보정은 생략합니다.
 
 옵션:
   --gmt        고정 GMT 시차 (기본: 실행 환경의 현재 시차, -12:00~+14:00)
@@ -16,6 +26,9 @@ const HELP_TEXT = `사용법: saju8z --date YYYY-MM-DD --time HH:mm [--gmt ±HH:
   --help, -h   도움말
 
 예제:
+  saju8z
+  saju8z --dt 19980305
+  saju8z --dt 199803051100
   saju8z --date 2000-02-29 --time 00:10
   saju8z --date 2000-02-29 --time 00:10 --gmt +09:00
   saju8z --date 2000-02-29 --time 00:10 --gmt=-05:00 --format json
@@ -32,7 +45,35 @@ function getCurrentGmtOffset() {
   return `${sign}${hours}:${remainder}`;
 }
 
-const VALUE_OPTIONS = new Set(["--date", "--time", "--gmt", "--calendar", "--format"]);
+async function readInteractiveArguments() {
+  const reader = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    terminal: Boolean(process.stdin.isTTY && process.stderr.isTTY),
+    crlfDelay: Infinity
+  });
+  const answers = reader[Symbol.asyncIterator]();
+  /** @param {string} prompt */
+  async function ask(prompt) {
+    process.stderr.write(prompt);
+    const answer = await answers.next();
+    if (answer.done) {
+      throw new UserInputError("입력이 종료되었습니다. --date 또는 --dt를 사용하세요.");
+    }
+    return answer.value.trim();
+  }
+
+  try {
+    process.stderr.write("생년월일과 출생 시각을 입력하세요. 양력·현재 GMT 시차로 계산합니다.\n");
+    const date = await ask("생년월일 (YYYY-MM-DD, 예: 1998-03-05): ");
+    const time = await ask("출생 시각 (HH:mm, 예: 11:00 / 시간을 모르면 비워두고 Enter): ");
+    return time ? ["--date", date, "--time", time] : ["--date", date];
+  } finally {
+    reader.close();
+  }
+}
+
+const VALUE_OPTIONS = new Set(["--dt", "--date", "--time", "--gmt", "--calendar", "--format"]);
 
 /** @param {string[]} args */
 function parseOptions(args) {
@@ -57,12 +98,35 @@ function parseOptions(args) {
   return { values, leapMonth };
 }
 
+/** @param {Map<string, string>} values */
+function resolveDateTime(values) {
+  const dt = values.get("--dt");
+  if (dt !== undefined) {
+    if (values.has("--date") || values.has("--time")) {
+      throw new UserInputError("--dt는 --date 또는 --time과 함께 사용할 수 없습니다.");
+    }
+    if (![8, 12].includes(dt.length) || !/^\d+$/.test(dt)) {
+      throw new UserInputError(
+        "--dt는 YYYYMMDD 형식의 8자리 또는 YYYYMMDDHHmm 형식의 12자리 숫자여야 합니다."
+      );
+    }
+    return {
+      date: `${dt.slice(0, 4)}-${dt.slice(4, 6)}-${dt.slice(6, 8)}`,
+      ...(dt.length === 12 ? { time: `${dt.slice(8, 10)}:${dt.slice(10, 12)}` } : {})
+    };
+  }
+  const date = values.get("--date");
+  const time = values.get("--time");
+  if (!date) {
+    throw new UserInputError("--date 또는 --dt를 입력하세요.");
+  }
+  return { date, ...(time === undefined ? {} : { time }) };
+}
+
 /** @param {string[]} args */
 function parseArguments(args) {
   const { values, leapMonth } = parseOptions(args);
-  const date = values.get("--date");
-  const time = values.get("--time");
-  if (!date || !time) throw new UserInputError("--date, --time은 필수입니다.");
+  const { date, time } = resolveDateTime(values);
   const gmt = values.get("--gmt") ?? getCurrentGmtOffset();
   const calendar = values.get("--calendar") ?? "solar";
   if (calendar !== "solar" && calendar !== "lunar")
@@ -70,7 +134,10 @@ function parseArguments(args) {
   const format = values.get("--format") ?? "text";
   if (format !== "text" && format !== "json" && format !== "prompt")
     throw new UserInputError("출력 형식은 text, json 또는 prompt이어야 합니다.");
-  return { input: { date, time, gmt, calendar, leapMonth }, format };
+  return {
+    input: { date, ...(time === undefined ? {} : { time }), gmt, calendar, leapMonth },
+    format
+  };
 }
 
 try {
@@ -79,9 +146,11 @@ try {
   if (showHelp) {
     process.stdout.write(HELP_TEXT);
   } else {
-    const { input, format } = parseArguments(args);
+    const inputArgs = args.length === 0 ? await readInteractiveArguments() : args;
+    const { input, format } = parseArguments(inputArgs);
     const result = calculateSajuChart(input);
-    process.stdout.write(`${formatSajuChart(result, format)}\n`);
+    const leadingNewline = format === "text" ? "\n" : "";
+    process.stdout.write(`${leadingNewline}${formatSajuChart(result, format)}\n`);
   }
 } catch (error) {
   process.stderr.write(

package/dist/core.cjs

@@ -37,7 +37,9 @@ __export(core_exports, {
   addMinutes: () => addMinutes,
   applySolarTimeCorrection: () => applySolarTimeCorrection,
   branchIndex: () => branchIndex,
+  calculateDateTenGods: () => calculateDateTenGods,
   calculateDayPillar: () => calculateDayPillar,
+  calculateDayPillarFromDate: () => calculateDayPillarFromDate,
   calculateFourPillars: () => calculateFourPillars,
   calculateHourBranch: () => calculateHourBranch,
   calculateHourPillar: () => calculateHourPillar,
@@ -45,10 +47,12 @@ __export(core_exports, {
   calculateTenGod: () => calculateTenGod,
   calculateTenGods: () => calculateTenGods,
   calculateYearPillar: () => calculateYearPillar,
+  compareLocalDate: () => compareLocalDate,
   compareLocalDateTime: () => compareLocalDateTime,
   daysInMonth: () => daysInMonth,
   formatLocalDateTime: () => formatLocalDateTime,
   formatPillar: () => formatPillar,
+  getMonthBranchBySolarDate: () => getMonthBranchBySolarDate,
   getMonthBranchBySolarTerm: () => getMonthBranchBySolarTerm,
   getSolarTermDateTime: () => getSolarTermDateTime,
   hasLunarLeapMonth: () => hasLunarLeapMonth,
@@ -58,6 +62,7 @@ __export(core_exports, {
   lunarMonthDays: () => lunarMonthDays,
   lunarToSolar: () => lunarToSolar,
   monthBranchesInOrder: () => monthBranchesInOrder,
+  monthPillarFromBranch: () => monthPillarFromBranch,
   pillarFromIndex: () => pillarFromIndex,
   positiveModulo: () => positiveModulo,
   sexagenaryIndexOfPillar: () => sexagenaryIndexOfPillar,
@@ -74,7 +79,7 @@ var SUPPORTED_START_YEAR = 1900;
 var SUPPORTED_END_YEAR = 2100;
 
 // src/config/saju8z.ts
-var SAJU8Z_VERSION = "1.1.0";
+var SAJU8Z_VERSION = "1.2.0";
 var SAJU8Z_CALCULATION_PROFILE = "saju8z-fixed-gmt-kst-minus30-v1";
 var SAJU8Z_CORRECTION_MINUTES = -30;
 
@@ -312,6 +317,9 @@ function daysInMonth(year, month) {
 function isValidDate(year, month, day) {
   return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
 }
+function compareLocalDate(left, right) {
+  return left.year - right.year || left.month - right.month || left.day - right.day;
+}
 function compareLocalDateTime(left, right) {
   const keys = ["year", "month", "day", "hour", "minute"];
   for (const key of keys) {
@@ -1823,11 +1831,23 @@ function getMonthBranchBySolarTerm(dateTime) {
   }
   return selected;
 }
+function getMonthBranchBySolarDate(date) {
+  const rules = [...SOLAR_TERM_RULES].sort((left, right) => left.month - right.month);
+  let selected = "\uCD95";
+  for (const rule of rules) {
+    if (compareLocalDate(date, solarTermDateTime(date.year, rule)) >= 0)
+      selected = rule.monthBranch;
+  }
+  return selected;
+}
 
 // src/saju/calculateDayPillar.ts
 var JDN_TO_SEXAGENARY_OFFSET = 49;
 function calculateDayPillar(dateTime) {
-  const jdn = julianDayNumber(dateTime.year, dateTime.month, dateTime.day);
+  return calculateDayPillarFromDate(dateTime);
+}
+function calculateDayPillarFromDate(date) {
+  const jdn = julianDayNumber(date.year, date.month, date.day);
   return pillarFromIndex(positiveModulo(jdn + JDN_TO_SEXAGENARY_OFFSET, 60));
 }
 
@@ -1880,6 +1900,9 @@ var IN_MONTH_START_STEM_BY_YEAR_STEM = {
 };
 function calculateMonthPillar(dateTime, yearStem) {
   const branch = getMonthBranchBySolarTerm(dateTime);
+  return monthPillarFromBranch(branch, yearStem);
+}
+function monthPillarFromBranch(branch, yearStem) {
   const offsetFromIn = positiveModulo(branchIndex(branch) - branchIndex("\uC778"), 12);
   const stem = stemAt(IN_MONTH_START_STEM_BY_YEAR_STEM[yearStem] + offsetFromIn);
   return { stem, branch };
@@ -1933,14 +1956,20 @@ function calculateTenGod(dayStem, targetStem) {
 
 // src/saju/calculateTenGods.ts
 function calculateTenGods(fourPillars) {
+  const dayStem = fourPillars.day.stem;
+  return {
+    ...calculateDateTenGods(fourPillars),
+    hourStem: calculateTenGod(dayStem, fourPillars.hour.stem),
+    hourBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.hour.branch].mainHiddenStem)
+  };
+}
+function calculateDateTenGods(fourPillars) {
   const dayStem = fourPillars.day.stem;
   return {
     yearStem: calculateTenGod(dayStem, fourPillars.year.stem),
     yearBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.year.branch].mainHiddenStem),
     monthStem: calculateTenGod(dayStem, fourPillars.month.stem),
     monthBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.month.branch].mainHiddenStem),
-    dayBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.day.branch].mainHiddenStem),
-    hourStem: calculateTenGod(dayStem, fourPillars.hour.stem),
-    hourBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.hour.branch].mainHiddenStem)
+    dayBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.day.branch].mainHiddenStem)
   };
 }

package/dist/core.js

@@ -5,7 +5,7 @@ var SUPPORTED_START_YEAR = 1900;
 var SUPPORTED_END_YEAR = 2100;
 
 // src/config/saju8z.ts
-var SAJU8Z_VERSION = "1.1.0";
+var SAJU8Z_VERSION = "1.2.0";
 var SAJU8Z_CALCULATION_PROFILE = "saju8z-fixed-gmt-kst-minus30-v1";
 var SAJU8Z_CORRECTION_MINUTES = -30;
 
@@ -243,6 +243,9 @@ function daysInMonth(year, month) {
 function isValidDate(year, month, day) {
   return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
 }
+function compareLocalDate(left, right) {
+  return left.year - right.year || left.month - right.month || left.day - right.day;
+}
 function compareLocalDateTime(left, right) {
   const keys = ["year", "month", "day", "hour", "minute"];
   for (const key of keys) {
@@ -1754,11 +1757,23 @@ function getMonthBranchBySolarTerm(dateTime) {
   }
   return selected;
 }
+function getMonthBranchBySolarDate(date) {
+  const rules = [...SOLAR_TERM_RULES].sort((left, right) => left.month - right.month);
+  let selected = "\uCD95";
+  for (const rule of rules) {
+    if (compareLocalDate(date, solarTermDateTime(date.year, rule)) >= 0)
+      selected = rule.monthBranch;
+  }
+  return selected;
+}
 
 // src/saju/calculateDayPillar.ts
 var JDN_TO_SEXAGENARY_OFFSET = 49;
 function calculateDayPillar(dateTime) {
-  const jdn = julianDayNumber(dateTime.year, dateTime.month, dateTime.day);
+  return calculateDayPillarFromDate(dateTime);
+}
+function calculateDayPillarFromDate(date) {
+  const jdn = julianDayNumber(date.year, date.month, date.day);
   return pillarFromIndex(positiveModulo(jdn + JDN_TO_SEXAGENARY_OFFSET, 60));
 }
 
@@ -1811,6 +1826,9 @@ var IN_MONTH_START_STEM_BY_YEAR_STEM = {
 };
 function calculateMonthPillar(dateTime, yearStem) {
   const branch = getMonthBranchBySolarTerm(dateTime);
+  return monthPillarFromBranch(branch, yearStem);
+}
+function monthPillarFromBranch(branch, yearStem) {
   const offsetFromIn = positiveModulo(branchIndex(branch) - branchIndex("\uC778"), 12);
   const stem = stemAt(IN_MONTH_START_STEM_BY_YEAR_STEM[yearStem] + offsetFromIn);
   return { stem, branch };
@@ -1864,15 +1882,21 @@ function calculateTenGod(dayStem, targetStem) {
 
 // src/saju/calculateTenGods.ts
 function calculateTenGods(fourPillars) {
+  const dayStem = fourPillars.day.stem;
+  return {
+    ...calculateDateTenGods(fourPillars),
+    hourStem: calculateTenGod(dayStem, fourPillars.hour.stem),
+    hourBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.hour.branch].mainHiddenStem)
+  };
+}
+function calculateDateTenGods(fourPillars) {
   const dayStem = fourPillars.day.stem;
   return {
     yearStem: calculateTenGod(dayStem, fourPillars.year.stem),
     yearBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.year.branch].mainHiddenStem),
     monthStem: calculateTenGod(dayStem, fourPillars.month.stem),
     monthBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.month.branch].mainHiddenStem),
-    dayBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.day.branch].mainHiddenStem),
-    hourStem: calculateTenGod(dayStem, fourPillars.hour.stem),
-    hourBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.hour.branch].mainHiddenStem)
+    dayBranch: calculateTenGod(dayStem, BRANCH_INFO[fourPillars.day.branch].mainHiddenStem)
   };
 }
 export {
@@ -1894,7 +1918,9 @@ export {
   addMinutes,
   applySolarTimeCorrection,
   branchIndex,
+  calculateDateTenGods,
   calculateDayPillar,
+  calculateDayPillarFromDate,
   calculateFourPillars,
   calculateHourBranch,
   calculateHourPillar,
@@ -1902,10 +1928,12 @@ export {
   calculateTenGod,
   calculateTenGods,
   calculateYearPillar,
+  compareLocalDate,
   compareLocalDateTime,
   daysInMonth,
   formatLocalDateTime,
   formatPillar,
+  getMonthBranchBySolarDate,
   getMonthBranchBySolarTerm,
   getSolarTermDateTime,
   hasLunarLeapMonth,
@@ -1915,6 +1943,7 @@ export {
   lunarMonthDays,
   lunarToSolar,
   monthBranchesInOrder,
+  monthPillarFromBranch,
   pillarFromIndex,
   positiveModulo,
   sexagenaryIndexOfPillar,

package/dist/format.cjs

@@ -242,7 +242,9 @@ function formatDayStem(stem) {
   return `${stem}${ELEMENT_NAMES[element]}(${STEM_HANJA[stem].hanja}${element})`;
 }
 function describePillar(result, position) {
-  const { stem, branch } = result.fourPillars[position];
+  const value = result.fourPillars[position];
+  if (value === null) return null;
+  const { stem, branch } = value;
   const stemHanja = STEM_HANJA[stem].hanja;
   const branchHanja = BRANCH_HANJA[branch].hanja;
   return {
@@ -259,17 +261,27 @@ function describePillar(result, position) {
 
 // src/output/formatSajuText.ts
 function formatDateTime(value) {
+  if (value.hour === null) {
+    return `${String(value.year).padStart(4, "0")}-${String(value.month).padStart(2, "0")}-${String(value.day).padStart(2, "0")}`;
+  }
   return formatLocalDateTime(value).replace("T", " ");
 }
 function formatSajuText(result) {
   const lines = [
     "[\uB9CC\uC138\uB825]",
-    `\uC591\uB825 \uD658\uC0B0 \uC2DC\uAC01: ${formatDateTime(result.normalizedDateTime)} (GMT+09:00)`,
-    `${SAJU8Z_CORRECTION_MINUTES}\uBD84 \uBCF4\uC815 \uD6C4 \uACC4\uC0B0 \uC2DC\uAC01: ${formatDateTime(result.calculationDateTime)}`,
+    ...result.normalizedDateTime.hour === null ? [
+      `\uC591\uB825 \uB0A0\uC9DC: ${formatDateTime(result.normalizedDateTime)}`,
+      "\uCD9C\uC0DD \uC2DC\uAC01: \uBBF8\uC0C1 (\uC0BC\uC8FC\uB9CC \uC81C\uACF5\uD558\uBA70 \uC2DC\uC8FC\uB294 \uCD94\uC815\uD558\uAC70\uB098 \uD574\uC11D\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.)",
+      "\uC2DC\uAC04 \uBBF8\uC0C1\uC73C\uB85C GMT \uD658\uC0B0\uACFC -30\uBD84 \uBCF4\uC815\uC740 \uC801\uC6A9\uD558\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4."
+    ] : [
+      `\uC591\uB825 \uD658\uC0B0 \uC2DC\uAC01: ${formatDateTime(result.normalizedDateTime)} (GMT+09:00)`,
+      `${SAJU8Z_CORRECTION_MINUTES}\uBD84 \uBCF4\uC815 \uD6C4 \uACC4\uC0B0 \uC2DC\uAC01: ${formatDateTime(result.calculationDateTime)}`
+    ],
     `\uC77C\uAC04: ${formatDayStem(result.fourPillars.day.stem)}`
   ];
   for (const position of ["year", "month", "day", "hour"]) {
     const pillar = describePillar(result, position);
+    if (pillar === null) continue;
     lines.push(
       "",
       `${pillar.label}: ${pillar.name}`,