@orrery/core 0.3.0 → 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,3 +1,5 @@
+**한국어** | [English](./README.en.md) | [中文](./README.zh.md) | [日本語](./README.ja.md)
+
 # @orrery/core
 
 브라우저/Node.js 환경에서 동작하는 동양·서양 점술 계산 엔진입니다.