@orrery/core 0.2.1 → 0.4.0

package/README.en.md

@@ -0,0 +1,241 @@
+[한국어](./README.md) | **English** | [中文](./README.zh.md) | [日本語](./README.ja.md)
+
+# @orrery/core
+
+A calculation engine for Eastern and Western divination that runs in browser and Node.js environments.
+
+- **四柱八字 (Four Pillars of Destiny)** — 60 干支 cycle, 十神, 12운성, 12신살, 大運, stem-branch interaction analysis
+- **紫微斗數 (Purple Star Astrology)** — 命盤 generation, 大限, 流年/流月 analysis
+- **Western Astrology Natal Chart** — Planet positions, houses, angles, aspects (pure TypeScript)
+
+No backend required. All calculations are performed on the client.
+
+**[Live Demo →](https://rath.github.io/orrery/)**
+
+## Credits
+
+- **Saju Perpetual Calendar** — Originally a Perl [perpetual calendar](http://afnmp3.homeip.net/~kohyc/calendar/cal20000.html) by Ko Young-chang, [ported to PHP](https://github.com/OOPS-ORG-PHP/Lunar) by Kim Jeong-gyun. In November 2018, Hwang Jang-ho ported it to Java and Python for personal use, then ported it to TypeScript in February 2026 using Claude Code (Opus 4.6).
+- **紫微斗數 Chart** — Built on the [lunar-javascript](https://www.npmjs.com/package/lunar-javascript) library; Claude (Opus 4.5) implemented it while researching Chinese-language references.
+- **Astrology Natal Chart** — The Moshier ephemeris from [Swiss Ephemeris](https://www.astro.com/swisseph/) ported to pure TypeScript.
+
+## Installation
+
+```bash
+npm install @orrery/core
+```
+
+## Usage
+
+### 四柱八字 (Four Pillars of Destiny)
+
+```typescript
+import { calculateSaju } from '@orrery/core/saju'
+import type { BirthInput } from '@orrery/core/types'
+
+const input: BirthInput = {
+  year: 1993, month: 3, day: 12,
+  hour: 9, minute: 45,
+  gender: 'M',
+}
+
+const result = calculateSaju(input)
+
+// Four Pillars (hour, day, month, year order)
+for (const p of result.pillars) {
+  console.log(p.pillar.ganzi)     // '乙巳', '壬辰', '乙卯', '癸酉'
+  console.log(p.stemSipsin)       // Heavenly Stem 十神
+  console.log(p.branchSipsin)     // Earthly Branch 十神
+  console.log(p.unseong)          // 12운성
+}
+
+// 大運 (Major Life Periods)
+for (const dw of result.daewoon) {
+  console.log(`${dw.ganzi} (age ${dw.age}~)`)
+}
+
+// Stem-Branch Interactions (合, 沖, 刑, 破, 害)
+for (const [key, pair] of result.relations.pairs) {
+  console.log(key, pair.stem, pair.branch)
+}
+```
+
+### 紫微斗數 (Purple Star Astrology)
+
+```typescript
+import { createChart, calculateLiunian, getDaxianList } from '@orrery/core/ziwei'
+
+// Generate 命盤
+const chart = createChart(1993, 3, 12, 9, 45, true)
+
+console.log(chart.mingGongZhi)     // 命宮 Earthly Branch
+console.log(chart.shenGongZhi)     // 身宮 Earthly Branch
+console.log(chart.wuXingJu.name)   // Five Elements Bureau (e.g., '水二局')
+
+// Stars in each palace
+for (const [name, palace] of Object.entries(chart.palaces)) {
+  const stars = palace.stars.map(s => {
+    const sihua = s.siHua ? `(${s.siHua})` : ''
+    return `${s.name}${s.brightness}${sihua}`
+  })
+  console.log(`${name} [${palace.ganZhi}]: ${stars.join(', ')}`)
+}
+
+// 大限 (Major Life Periods)
+const daxianList = getDaxianList(chart)
+for (const dx of daxianList) {
+  console.log(`${dx.ageStart}~${dx.ageEnd}세: ${dx.palaceName} ${dx.ganZhi}`)
+}
+
+// 流年 (Annual Fortune) — Fortune for a specific year
+const liunian = calculateLiunian(chart, 2026)
+console.log(liunian.natalPalaceAtMing) // Natal palace where 流年命宮 falls
+console.log(liunian.siHua)             // 流年 四化
+```
+
+### Western Astrology (Natal Chart)
+
+```typescript
+import { calculateNatal } from '@orrery/core/natal'
+import type { BirthInput } from '@orrery/core/types'
+
+const input: BirthInput = {
+  year: 1993, month: 3, day: 12,
+  hour: 9, minute: 45,
+  gender: 'M',
+  latitude: 37.5665,   // Seoul (optional, default: Seoul)
+  longitude: 126.9780,
+}
+
+const chart = await calculateNatal(input)
+
+// Planet positions
+for (const planet of chart.planets) {
+  console.log(`${planet.id}: ${planet.sign} ${planet.degreeInSign.toFixed(1)}°`)
+  // 'Sun: Pisces 21.6°'
+}
+
+// ASC / MC
+console.log(`ASC: ${chart.angles.asc.sign}`)
+console.log(`MC: ${chart.angles.mc.sign}`)
+
+// Houses (default: Placidus)
+for (const house of chart.houses) {
+  console.log(`House ${house.number}: ${house.sign} ${house.degreeInSign.toFixed(1)}°`)
+}
+
+// Aspects
+for (const aspect of chart.aspects) {
+  console.log(`${aspect.planet1} ${aspect.type} ${aspect.planet2} (orb: ${aspect.orb.toFixed(1)}°)`)
+}
+
+// Change house system (Koch)
+const kochChart = await calculateNatal(input, 'K')
+```
+
+### Low-Level API
+
+You can also use individual functions directly:
+
+```typescript
+import { getFourPillars, getDaewoon, getRelation } from '@orrery/core/pillars'
+import { STEM_INFO, ELEMENT_HANJA } from '@orrery/core/constants'
+
+// Calculate only the four pillars
+const [년주, 월주, 일주, 시주] = getFourPillars(1993, 3, 12, 9, 45)
+console.log(년주, 월주, 일주, 시주) // '癸酉', '乙卯', '壬辰', '乙巳'
+
+// 十神 relationship
+const relation = getRelation('壬', '乙')
+console.log(relation?.hanja) // '傷官'
+
+// Heavenly Stem Five Elements info
+console.log(STEM_INFO['壬']) // { yinyang: '+', element: 'water' }
+console.log(ELEMENT_HANJA['water']) // '水'
+```
+
+### City Data
+
+Provides Korean and world major city data for birth location input:
+
+```typescript
+import { SEOUL, filterCities, formatCityName } from '@orrery/core/cities'
+
+console.log(SEOUL) // { name: '서울', lat: 37.5665, lon: 126.9780 }
+
+// Supports Korean initial consonant search
+const results = filterCities('ㅂㅅ')  // Matches '부산'
+console.log(formatCityName(results[0])) // '부산'
+```
+
+## Running Examples
+
+After cloning the repository, you can run the example scripts directly:
+
+```bash
+git clone https://github.com/rath/orrery.git
+cd orrery
+bun install
+
+# 사주팔자
+bun packages/core/examples/saju.ts
+
+# 자미두수
+bun packages/core/examples/ziwei.ts
+
+# 서양 점성술 출생차트
+bun packages/core/examples/natal.ts
+```
+
+## Subpath Exports
+
+You can selectively import only the modules you need:
+
+| Path | Description |
+|------|-------------|
+| `@orrery/core` | Full barrel export |
+| `@orrery/core/saju` | `calculateSaju()` |
+| `@orrery/core/ziwei` | `createChart()`, `calculateLiunian()`, `getDaxianList()` |
+| `@orrery/core/natal` | `calculateNatal()`, zodiac/planet symbols, format functions |
+| `@orrery/core/pillars` | `getFourPillars()`, `getDaewoon()`, and other low-level APIs |
+| `@orrery/core/types` | All TypeScript types/interfaces |
+| `@orrery/core/constants` | Stems/branches, 十神, palace names, and other constant tables |
+| `@orrery/core/cities` | City data, search functions |
+
+## Dependencies
+
+| Package | Type | Purpose |
+|---------|------|---------|
+| `lunar-javascript` | dependency | Lunar calendar conversion (紫微斗數) |
+
+All features run as pure TypeScript with no external WASM or data file dependencies.
+
+## License
+
+[AGPL-3.0](../../LICENSE)
+
+<details>
+<summary>What is AGPL-3.0? (Plain English)</summary>
+
+### What you CAN do
+
+- **Use it personally** — Run and modify it freely on your own machine.
+- **Read and study the source code** — You are always welcome to learn from the code.
+- **Modify, improve, and redistribute** — You can fork and redistribute the code, provided you follow the conditions below.
+
+### What you MUST do
+
+- **Keep the same license (AGPL-3.0)** — Any derivative work that includes or modifies this code must also be released under AGPL-3.0.
+- **Disclose source code** — Unlike the standard GPL, the AGPL requires source disclosure **even when the software is offered as a web service**. If you modify this code and run it as a website, you must provide the modified source code to users upon request.
+- **State changes** — You must clearly indicate what you changed from the original.
+- **Preserve copyright notices** — Do not remove the original copyright and license notices.
+
+### What you CANNOT do
+
+- **Run a service with closed source** — Using a modified version of this code to operate a web service without disclosing the source is a license violation.
+- **Relicense** — You cannot redistribute AGPL code under a more permissive license such as MIT or Apache.
+
+### TL;DR
+
+> Use it freely, but if you modify it or offer it as a service, you must release the source code under AGPL-3.0.
+
+</details>

package/README.ja.md

@@ -0,0 +1,241 @@
+[한국어](./README.md) | [English](./README.en.md) | [中文](./README.zh.md) | **日本語**
+
+# @orrery/core
+
+ブラウザおよびNode.js環境で動作する東洋・西洋占術計算エンジンです。
+
+- **四柱八字** — 六十干支、十神、十二運星、十二神殺、大運、干支関係分析
+- **紫微斗數** — 命盤生成、大限、流年/流月分析
+- **西洋占星術出生チャート（Natal Chart）** — 惑星位置、ハウス、アングル、アスペクト（純粋TypeScript）
+
+バックエンド不要。すべての計算がクライアント上で実行されます。
+
+**[ライブデモ →](https://rath.github.io/orrery/)**
+
+## クレジット
+
+- **四柱万年暦** — 고영창（Ko Young-chang）氏のPerl [真万年暦](http://afnmp3.homeip.net/~kohyc/calendar/cal20000.html)を김정균（Kim Jeong-gyun）氏が[PHPに移植](https://github.com/OOPS-ORG-PHP/Lunar)したものを、2018年11月に황장호（Hwang Jang-ho）がJavaとPythonに移植して使用、2026年2月にClaude Code（Opus 4.6）でTypeScriptに移植
+- **紫微斗數命盤** — [lunar-javascript](https://www.npmjs.com/package/lunar-javascript)ライブラリをベースに、Claude（Opus 4.5）が中国語文献を調査しながら実装
+- **占星術出生チャート** — [Swiss Ephemeris](https://www.astro.com/swisseph/)のMoshier理論を純粋なTypeScriptに移植
+
+## インストール
+
+```bash
+npm install @orrery/core
+```
+
+## 使い方
+
+### 四柱八字
+
+```typescript
+import { calculateSaju } from '@orrery/core/saju'
+import type { BirthInput } from '@orrery/core/types'
+
+const input: BirthInput = {
+  year: 1993, month: 3, day: 12,
+  hour: 9, minute: 45,
+  gender: 'M',
+}
+
+const result = calculateSaju(input)
+
+// 四柱（時、日、月、年の順）
+for (const p of result.pillars) {
+  console.log(p.pillar.ganzi)     // '乙巳', '壬辰', '乙卯', '癸酉'
+  console.log(p.stemSipsin)       // 天干十神
+  console.log(p.branchSipsin)     // 地支十神
+  console.log(p.unseong)          // 十二運星
+}
+
+// 大運
+for (const dw of result.daewoon) {
+  console.log(`${dw.ganzi} (${dw.age}세~)`)
+}
+
+// 干支関係（合、沖、刑、破、害）
+for (const [key, pair] of result.relations.pairs) {
+  console.log(key, pair.stem, pair.branch)
+}
+```
+
+### 紫微斗數
+
+```typescript
+import { createChart, calculateLiunian, getDaxianList } from '@orrery/core/ziwei'
+
+// 命盤を生成
+const chart = createChart(1993, 3, 12, 9, 45, true)
+
+console.log(chart.mingGongZhi)     // 命宮の地支
+console.log(chart.shenGongZhi)     // 身宮の地支
+console.log(chart.wuXingJu.name)   // 五行局（例：'水二局'）
+
+// 各宮位の星曜を確認
+for (const [name, palace] of Object.entries(chart.palaces)) {
+  const stars = palace.stars.map(s => {
+    const sihua = s.siHua ? `(${s.siHua})` : ''
+    return `${s.name}${s.brightness}${sihua}`
+  })
+  console.log(`${name} [${palace.ganZhi}]: ${stars.join(', ')}`)
+}
+
+// 大限
+const daxianList = getDaxianList(chart)
+for (const dx of daxianList) {
+  console.log(`${dx.ageStart}~${dx.ageEnd}세: ${dx.palaceName} ${dx.ganZhi}`)
+}
+
+// 流年 — 特定の年の運勢
+const liunian = calculateLiunian(chart, 2026)
+console.log(liunian.natalPalaceAtMing) // 流年命宮が位置する本命盤の宮位
+console.log(liunian.siHua)             // 流年四化
+```
+
+### 西洋占星術（Natal Chart）
+
+```typescript
+import { calculateNatal } from '@orrery/core/natal'
+import type { BirthInput } from '@orrery/core/types'
+
+const input: BirthInput = {
+  year: 1993, month: 3, day: 12,
+  hour: 9, minute: 45,
+  gender: 'M',
+  latitude: 37.5665,   // ソウル（任意、デフォルト：ソウル）
+  longitude: 126.9780,
+}
+
+const chart = await calculateNatal(input)
+
+// 惑星位置
+for (const planet of chart.planets) {
+  console.log(`${planet.id}: ${planet.sign} ${planet.degreeInSign.toFixed(1)}°`)
+  // 'Sun: Pisces 21.6°'
+}
+
+// ASC / MC
+console.log(`ASC: ${chart.angles.asc.sign}`)
+console.log(`MC: ${chart.angles.mc.sign}`)
+
+// ハウス（デフォルト：Placidus）
+for (const house of chart.houses) {
+  console.log(`House ${house.number}: ${house.sign} ${house.degreeInSign.toFixed(1)}°`)
+}
+
+// アスペクト
+for (const aspect of chart.aspects) {
+  console.log(`${aspect.planet1} ${aspect.type} ${aspect.planet2} (orb: ${aspect.orb.toFixed(1)}°)`)
+}
+
+// ハウスシステムの変更（Koch）
+const kochChart = await calculateNatal(input, 'K')
+```
+
+### 低レベルAPI
+
+個別の関数を直接使用することもできます：
+
+```typescript
+import { getFourPillars, getDaewoon, getRelation } from '@orrery/core/pillars'
+import { STEM_INFO, ELEMENT_HANJA } from '@orrery/core/constants'
+
+// 四柱のみ計算
+const [년주, 월주, 일주, 시주] = getFourPillars(1993, 3, 12, 9, 45)
+console.log(년주, 월주, 일주, 시주) // '癸酉', '乙卯', '壬辰', '乙巳'
+
+// 十神関係
+const relation = getRelation('壬', '乙')
+console.log(relation?.hanja) // '傷官'
+
+// 天干五行情報
+console.log(STEM_INFO['壬']) // { yinyang: '+', element: 'water' }
+console.log(ELEMENT_HANJA['water']) // '水'
+```
+
+### 都市データ
+
+出生地入力に活用できる韓国・世界の主要都市データを提供しています：
+
+```typescript
+import { SEOUL, filterCities, formatCityName } from '@orrery/core/cities'
+
+console.log(SEOUL) // { name: '서울', lat: 37.5665, lon: 126.9780 }
+
+// 韓国語の初声検索対応
+const results = filterCities('ㅂㅅ')  // '부산'にマッチ
+console.log(formatCityName(results[0])) // '부산'
+```
+
+## サンプルの実行
+
+リポジトリをクローンした後、すぐに実行できるサンプルスクリプトがあります：
+
+```bash
+git clone https://github.com/rath/orrery.git
+cd orrery
+bun install
+
+# 사주팔자
+bun packages/core/examples/saju.ts
+
+# 자미두수
+bun packages/core/examples/ziwei.ts
+
+# 서양 점성술 출생차트
+bun packages/core/examples/natal.ts
+```
+
+## Subpath Exports
+
+必要なモジュールのみを選択的にインポートできます：
+
+| パス | 説明 |
+|------|------|
+| `@orrery/core` | 全体のbarrel export |
+| `@orrery/core/saju` | `calculateSaju()` |
+| `@orrery/core/ziwei` | `createChart()`, `calculateLiunian()`, `getDaxianList()` |
+| `@orrery/core/natal` | `calculateNatal()`、星座/惑星シンボル、フォーマット関数 |
+| `@orrery/core/pillars` | `getFourPillars()`, `getDaewoon()` 等の低レベルAPI |
+| `@orrery/core/types` | すべてのTypeScript型/インターフェース |
+| `@orrery/core/constants` | 天干/地支、十神、宮位名などの定数テーブル |
+| `@orrery/core/cities` | 都市データ、検索関数 |
+
+## 依存関係
+
+| パッケージ | タイプ | 用途 |
+|------------|--------|------|
+| `lunar-javascript` | dependency | 旧暦変換（紫微斗數） |
+
+外部のWASMやデータファイルへの依存なく、すべての機能が純粋なTypeScriptで動作します。
+
+## ライセンス
+
+[AGPL-3.0](../../LICENSE)
+
+<details>
+<summary>AGPL-3.0とは？（わかりやすい説明）</summary>
+
+### 自由にできること
+
+- **個人的に使用** — 自分のコンピュータで自由に実行・修正できます。
+- **ソースコードを読んで学ぶ** — コードを見て学ぶことはいつでも歓迎です。
+- **修正・改善して再配布** — コードを修正して再配布できます。ただし、以下の条件を守る必要があります。
+
+### 必ず守ること
+
+- **同じライセンス（AGPL-3.0）を維持** — このコードを修正または含めて配布する場合、その成果物も必ずAGPL-3.0で公開しなければなりません。
+- **ソースコードの公開義務** — 通常のGPLと異なり、AGPLは**Webサービスとして提供する場合にも**ソースコードを公開する必要があります。例えば、このコードを修正してウェブサイトとして運営する場合、ユーザーの要求に応じて修正されたソースコードを提供しなければなりません。
+- **変更内容の明示** — 元のコードから何を変更したかわかるように表示する必要があります。
+- **著作権表示の維持** — 元の著作権表示とライセンス文言を削除してはいけません。
+
+### できないこと
+
+- **ソース非公開でサービス運営** — このコードを修正してWebサービスを運営しながらソースを公開しないことはライセンス違反です。
+- **ライセンスの変更** — AGPLコードをMIT、Apacheなどのより寛容なライセンスに変更して配布することはできません。
+
+### 一言まとめ
+
+> 自由に使えますが、修正したりサービスとして提供する場合は、ソースコードをAGPL-3.0で公開してください。
+
+</details>

package/README.md

@@ -1,10 +1,12 @@
+**한국어** | [English](./README.en.md) | [中文](./README.zh.md) | [日本語](./README.ja.md)
+
 # @orrery/core
 
 브라우저/Node.js 환경에서 동작하는 동양·서양 점술 계산 엔진입니다.
 
 - **사주팔자(四柱八字)** — 60갑자, 십신, 12운성, 12신살, 대운, 간지 관계 분석
 - **자미두수(紫微斗數)** — 명반(命盤) 생성, 대한(大限), 유년(流年)/유월(流月) 분석
-- **서양 점성술 출생차트(Natal Chart)** — 행성 위치, 하우스, 앵글, 애스펙트 (Swiss Ephemeris WASM)
+- **서양 점성술 출생차트(Natal Chart)** — 행성 위치, 하우스, 앵글, 애스펙트 (순수 TypeScript)
 
 백엔드 불필요. 모든 계산이 클라이언트에서 수행됩니다.
 
@@ -12,9 +14,9 @@
 
 ## 크레딧
 
-- **사주 만세력** — 고영창님의 Perl [진짜만세력](http://afnmp3.homeip.net/~kohyc/calendar/cal20000.html)를 김정균님이 [PHP로 포팅](https://github.com/OOPS-ORG-PHP/Lunar)한 것을, 2018년 11월 황장호가 Java와 Python으로 재포팅하여 사용해오다가, 2026년 2월 Claude Code (Opus 4.6)로 TypeScript로 포팅
+- **사주 만세력** — 고영창님의 Perl [진짜만세력](http://afnmp3.homeip.net/~kohyc/calendar/cal20000.html)을 김정균님이 [PHP로 포팅](https://github.com/OOPS-ORG-PHP/Lunar)한 것을, 2018년 11월 황장호가 Java와 Python으로 포팅하여 사용해오다가, 2026년 2월 Claude Code (Opus 4.6)로 TypeScript로 포팅
 - **자미두수 명반** — [lunar-javascript](https://www.npmjs.com/package/lunar-javascript) 라이브러리 기반으로 Claude (Opus 4.5)가 중국어 문헌을 리서치하며 구현
-- **점성술 출생차트** — [Swiss Ephemeris](https://github.com/arturania/swisseph)를 WASM으로 빌드한 [swisseph-wasm](https://www.npmjs.com/package/swisseph-wasm) 기반
+- **점성술 출생차트** — [Swiss Ephemeris](https://www.astro.com/swisseph/)의 Moshier 이론을 순수 TypeScript로 포팅
 
 ## 설치
 
@@ -22,14 +24,6 @@
 npm install @orrery/core
 ```
 
-서양 점성술(natal) 기능을 사용하려면 `swisseph-wasm`도 설치하세요:
-
-```bash
-npm install swisseph-wasm
-```
-
-> `swisseph-wasm`은 optional peer dependency입니다. 사주/자미두수만 사용한다면 설치하지 않아도 됩니다.
-
 ## 사용법
 
 ### 사주팔자 (四柱八字)
@@ -212,10 +206,36 @@ bun packages/core/examples/natal.ts
 | 패키지 | 유형 | 용도 |
 |--------|------|------|
 | `lunar-javascript` | dependency | 음력 변환 (자미두수) |
-| `swisseph-wasm` | optional peer | Swiss Ephemeris WASM (서양 점성술) |
 
-`swisseph-wasm`을 설치하지 않으면 사주/자미두수만 사용 가능합니다.
+외부 WASM이나 데이터 파일 의존성 없이 모든 기능이 순수 TypeScript로 동작합니다.
 
 ## 라이선스
 
-MIT
+[AGPL-3.0](../../LICENSE)
+
+<details>
+<summary>AGPL-3.0이 뭔가요? (쉬운 설명)</summary>
+
+### 자유롭게 할 수 있는 것
+
+- **개인적으로 사용** — 본인 컴퓨터에서 마음대로 실행하고 수정해도 됩니다.
+- **소스 코드를 읽고 공부** — 코드를 보고 배우는 건 언제든 환영합니다.
+- **수정·개선 후 재배포** — 코드를 고쳐서 다시 배포할 수 있습니다. 단, 아래 조건을 지켜야 합니다.
+
+### 반드시 지켜야 하는 것
+
+- **같은 라이선스(AGPL-3.0) 유지** — 이 코드를 수정하거나 포함해서 배포할 때, 그 결과물도 반드시 AGPL-3.0으로 공개해야 합니다.
+- **소스 코드 공개 의무** — 일반적인 GPL과 달리, AGPL은 **웹 서비스로 제공하는 경우에도** 소스 코드를 공개해야 합니다. 예를 들어 이 코드를 수정해서 웹사이트로 운영하면, 사용자가 요청할 때 수정된 소스 코드를 제공해야 합니다.
+- **변경 사항 명시** — 원본에서 무엇을 바꿨는지 알 수 있도록 표시해야 합니다.
+- **저작권 표시 유지** — 원본의 저작권 표시와 라이선스 문구를 지우면 안 됩니다.
+
+### 할 수 없는 것
+
+- **소스 비공개 상태로 서비스 운영** — 이 코드를 수정해서 웹 서비스를 만들면서 소스를 공개하지 않는 것은 라이선스 위반입니다.
+- **다른 라이선스로 변경** — AGPL 코드를 MIT, Apache 등 더 허용적인 라이선스로 바꿔서 배포할 수 없습니다.
+
+### 한줄 요약
+
+> 마음껏 쓰되, 수정하거나 서비스로 제공할 경우 소스 코드를 AGPL-3.0으로 공개하세요.
+
+</details>