Add LiuNian & LiuYue generators with DaYun integration and unit tests

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.DS_Store
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -1 +1,56 @@
-See you later
+# LiuNian & LiuYue Generators
+
+Utilities for producing LiuNian (annual) and LiuYue (monthly) Heavenly Stem/Earthly Branch pillars within user-defined ranges. Each generated entry keeps track of the DaYun (great luck) cycle it belongs to, making it easy to analyse transitions across multiple cycles.
+
+## Installation
+
+```bash
+npm install
+```
+
+## Usage
+
+```javascript
+const { generateLiuNian, generateLiuYue } = require('./src/pillars');
+
+const daYunCycles = [
+  {
+    id: 'dy1',
+    name: 'First Luck',
+    startYear: 2000,
+    length: 10,
+    startPillar: '甲子',
+    startMonthPillar: '甲子',
+  },
+  {
+    id: 'dy2',
+    name: 'Second Luck',
+    startYear: 2010,
+    length: 10,
+    startPillar: '甲戌',
+    startMonthPillar: '甲子',
+  },
+];
+
+const annualPillars = generateLiuNian(daYunCycles, { fromYear: 2005, toYear: 2014 });
+const monthlyPillars = generateLiuYue(daYunCycles, { from: { year: 2009, month: 10 }, to: { year: 2010, month: 3 } });
+
+console.log(annualPillars.map((entry) => `${entry.year} ${entry.pillar.label}`));
+console.log(monthlyPillars.map((entry) => `${entry.year}-${entry.month} ${entry.pillar.label}`));
+```
+
+## Sample scenario
+
+A runnable scenario is provided in `examples/sample-scenario.js`:
+
+```bash
+node examples/sample-scenario.js
+```
+
+The script prints the LiuNian pillars from 2005 to 2014 alongside a focused LiuYue slice that spans late 2009 to early 2010, illustrating how the DaYun association flows across cycles.
+
+## Tests
+
+```bash
+npm test
+```

examples/sample-scenario.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { generateLiuNian, generateLiuYue } = require('../src/pillars');
+
+const daYunCycles = [
+  {
+    id: 'dy1',
+    name: 'First Luck',
+    startYear: 2000,
+    length: 10,
+    startPillar: '甲子',
+    startMonthPillar: '甲子',
+  },
+  {
+    id: 'dy2',
+    name: 'Second Luck',
+    startYear: 2010,
+    length: 10,
+    startPillar: '甲戌',
+    startMonthPillar: '甲子',
+  },
+];
+
+const annualRange = { fromYear: 2005, toYear: 2014 };
+const monthlyRange = { from: { year: 2009, month: 10 }, to: { year: 2010, month: 3 } };
+
+const annualPillars = generateLiuNian(daYunCycles, annualRange);
+const monthlyPillars = generateLiuYue(daYunCycles, monthlyRange);
+
+console.log('Annual pillars (2005-2014):');
+annualPillars.forEach((entry) => {
+  console.log(`${entry.year} ${entry.pillar.label} — ${entry.daYun.name}`);
+});
+
+console.log('\nMonthly pillars spanning late 2009 to early 2010:');
+monthlyPillars.forEach((entry) => {
+  const monthLabel = String(entry.month).padStart(2, '0');
+  console.log(`${entry.year}-${monthLabel} ${entry.pillar.label} — ${entry.daYun.name}`);
+});

package.json

@@ -0,0 +1,18 @@
+{
+  "name": "liunian-liuyue-generators",
+  "version": "1.0.0",
+  "description": "Utilities to generate LiuNian (annual) and LiuYue (monthly) pillars linked to DaYun cycles.",
+  "main": "src/pillars.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "liunian",
+    "liuyue",
+    "dayun",
+    "bazi",
+    "pillars"
+  ],
+  "author": "",
+  "license": "MIT"
+}