@nhatnguyet/cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,26 +4,28 @@
4
4
  Japanese lunar calendars in your terminal.** Charts print as grids, or as JSON
5
5
  and SVG. English by default, Vietnamese and Chinese with `--lang`. Runs
6
6
  locally with the [Nhat Nguyet](https://nhatnguyet.org/en/ma-nguon-mo)
7
- libraries, checked against 17,291 shared test vectors and NASA, IMCCE data.
7
+ libraries, checked against 17,291 core test vectors (18,819 including school options and
8
+ auspicious hours) and NASA, IMCCE data.
8
9
 
9
10
  ```bash
10
11
  npx @nhatnguyet/cli lunar 1985-01-21 --country CN
11
12
  ```
12
13
 
13
14
  ```text
14
- ┌────────────┬───────────────┐
15
- │ Gregorian │ 1985-01-21 │
16
- │ Lunar │ 1984-12-01 │
17
- │ Year │ Giáp Tý · Rat │
18
- │ Month │ Đinh Sửu │
19
- │ Day │ Canh Thân │
20
- │ Solar term │ Major Cold │
21
- │ Calendar │ CN (UTC+8) │
22
- └────────────┴───────────────┘
15
+ ┌────────────┬──────────────┐
16
+ │ Gregorian │ 1985-01-21 │
17
+ │ Lunar │ 1984-12-01 │
18
+ │ Year │ Jia Zi · Rat │
19
+ │ Month │ Ding Chou │
20
+ │ Day │ Geng Shen │
21
+ │ Solar term │ Major Cold │
22
+ │ Calendar │ CN (UTC+8) │
23
+ └────────────┴──────────────┘
23
24
  ```
24
25
 
25
26
  Without `--country CN` the same day is Tết, `1985-01-01`, on the Vietnamese
26
- calendar (UTC+7).
27
+ calendar (UTC+7). Stems and branches print in pinyin; `--terms han` prints
28
+ 甲子, `--terms vi` the Sino-Vietnamese Giáp Tý.
27
29
 
28
30
  ## Install
29
31
 
@@ -37,31 +39,47 @@ Node.js 18 or newer. The Python package prints the same text:
37
39
  ## Commands
38
40
 
39
41
  ```text
40
- nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name "..."] [--year 2026]
41
- nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female>
42
+ nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name "..."] [--year 2026] [school options]
43
+ nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female> [--zi-hour ...]
42
44
  nhatnguyet lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]
43
45
  nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]
44
46
  nhatnguyet terms <year> [--country ...]
47
+ nhatnguyet hours <YYYY-MM-DD> auspicious and inauspicious double hours of a day
45
48
  nhatnguyet numerology "<full name>" <YYYY-MM-DD> [--today YYYY-MM-DD]
46
- nhatnguyet festivals <year>
49
+ nhatnguyet festivals <year> [--ics]
47
50
  ```
48
51
 
52
+ Each command also answers to the name of the matching MCP tool: `cast_ziwei`
53
+ (and the older `cast_zi_wei`, `zi_wei`), `cast_bazi`, `lunar_convert`,
54
+ `solar_terms`.
55
+
49
56
  | Option | Meaning |
50
57
  |---|---|
51
58
  | `--lang en\|vi\|zh` | language of the result (default `en`) |
59
+ | `--terms pinyin\|han\|vi` | English only: stems, branches, the Four Transformations as pinyin (default, `Geng Wu`, `Hua Ji`), Chinese characters or Sino-Vietnamese |
52
60
  | `--json` | print JSON instead of text |
53
61
  | `--svg <file>` | also write the chart as SVG (`ziwei`, `bazi`, `numerology`) |
62
+ | `--ics` | `festivals`: print an iCalendar (`.ics`) file instead |
54
63
  | `--theme dark` | dark SVG |
55
- | `--no-color` | no ANSI colours (also when `NO_COLOR` is set or output is not a terminal) |
64
+ | `--no-color` | no ANSI colors (also when `NO_COLOR` is set or output is not a terminal) |
65
+
66
+ School options (`--fire-bell`, `--leap-month`, `--transformations`,
67
+ `--heavenly-kitchen`, `--injury-messenger`, `--zi-hour`) switch to the rule of
68
+ another named book where the books disagree; `nhatnguyet --help` lists their
69
+ values and
70
+ [docs/schools.md](https://github.com/Nhat-Nguyet/nhatnguyet-lunar-ziwei-bazi-numerology/blob/main/docs/schools.md)
71
+ names the sources.
56
72
 
57
- Times are clock times; the Tý double hour runs 23:00 to 00:59. Dates and times
73
+ Times are clock times; the Zi (Rat) double hour runs 23:00 to 00:59. Dates and times
58
74
  are read as Vietnam time (UTC+7) unless `--country` says otherwise.
59
75
 
60
76
  ```bash
61
77
  nhatnguyet ziwei 1990-09-19 20:00 male --year 2026 # 12-palace grid, ten-year periods, patterns
62
78
  nhatnguyet bazi 1990-09-19 female # birth time unknown: three pillars
63
- nhatnguyet solar 2023-02-01 --leap # 2023-03-22
79
+ nhatnguyet solar 2023-02-01 --leap # table for 2023-03-22, like lunar
64
80
  nhatnguyet numerology "Nguyen Van An" 1990-09-19 --today 2026-11-19
81
+ nhatnguyet hours 2027-02-06 # the twelve double hours of Tết 2027
82
+ nhatnguyet festivals 2027 --ics > festivals-2027.ics # the year's festivals for a calendar app
65
83
  nhatnguyet ziwei 1990-09-19 20:00 male --svg chart.svg --theme dark
66
84
  ```
67
85
 
package/dist/cli.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  /** Version printed by --version. */
3
- export declare const VERSION = "0.1.0";
4
- export declare const HELP = "nhatnguyet: Zi Wei Dou Shu, BaZi, lunar calendar, numerology, Vietnamese festivals\n\nUsage:\n nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name \"...\"] [--year 2026]\n nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female>\n nhatnguyet lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]\n nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]\n nhatnguyet terms <year> [--country ...]\n nhatnguyet numerology \"<full name>\" <YYYY-MM-DD> [--today YYYY-MM-DD]\n nhatnguyet festivals <year>\n\nOptions:\n --lang en|vi|zh language of the result (default en)\n --json print JSON instead of text\n --svg <file> also write the chart as SVG (ziwei, bazi, numerology)\n --theme dark dark SVG\n --no-color no ANSI colours (also when NO_COLOR is set or output is not a terminal)\n -h, --help this help\n -v, --version version\n\nTimes are clock times; the T\u00FD double hour runs 23:00 to 00:59. Dates and times\nare read as Vietnam time (UTC+7) unless --country says otherwise (lunar, solar,\nterms). Docs: https://nhatnguyet.org/ma-nguon-mo";
3
+ export declare const VERSION = "0.3.0";
4
+ export declare const HELP = "nhatnguyet: Zi Wei Dou Shu, BaZi, lunar calendar, numerology, Vietnamese festivals\n\nUsage:\n nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name \"...\"] [--year 2026] [school options]\n nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female> [--zi-hour ...]\n nhatnguyet lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]\n nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]\n nhatnguyet terms <year> [--country ...]\n nhatnguyet hours <YYYY-MM-DD> auspicious and inauspicious double hours of a day\n nhatnguyet numerology \"<full name>\" <YYYY-MM-DD> [--today YYYY-MM-DD]\n nhatnguyet festivals <year> [--ics]\n\nOptions:\n --lang en|vi|zh language of the result (default en)\n --terms pinyin|han|vi English only: stems, branches and transformations as\n pinyin (default, \"Geng Wu\"), Chinese characters or Sino-Vietnamese\n --json print JSON instead of text\n --svg <file> also write the chart as SVG (ziwei, bazi, numerology)\n --ics festivals: print an iCalendar (.ics) file instead\n --theme dark dark SVG\n --no-color no ANSI colours (also when NO_COLOR is set or output is not a terminal)\n\nSchool options (where the books disagree; default first, sources in docs/schools.md):\n --fire-bell vietnamese|quanshu|swap-for-female|swap-for-yin-male-yang-female\n --leap-month whole|split-at-15|next-month\n --transformations vietnamese|quanshu|zhongzhou (Geng year row)\n --heavenly-kitchen vietnamese|chinese (Gui year)\n --injury-messenger standard|zhongzhou\n --zi-hour next-day-from-23|split-at-midnight (bazi: day pillar from 23:00 to 24:00)\n\n -h, --help this help\n -v, --version version\n\nTimes are clock times; the Zi (Rat) double hour runs 23:00 to 00:59. Dates and times\nare read as Vietnam time (UTC+7) unless --country says otherwise (lunar, solar,\nterms, ziwei). Docs: https://nhatnguyet.org/en/ma-nguon-mo";
5
5
  /** Parsed command line. */
6
6
  export interface Args {
7
7
  command: string;
package/dist/cli.js CHANGED
@@ -3,52 +3,82 @@
3
3
  // rồi in ra terminal (render.ts) hoặc JSON (--json).
4
4
  //
5
5
  // Command line for the Nhat Nguyet libraries.
6
- import { solarTerms, toLunar, toSolar } from "@nhatnguyet/am-lich";
6
+ import { auspiciousHours, checkTerms, solarTerms, toLunar, toSolar } from "@nhatnguyet/am-lich";
7
7
  import { castZiWei, decadeLuck, findPatterns, yearlyLuck, ziWeiSvg } from "@nhatnguyet/tu-vi";
8
8
  import { baZiSvg, castBaZi } from "@nhatnguyet/bat-tu";
9
9
  import { numerology, numerologySvg } from "@nhatnguyet/than-so-hoc";
10
10
  import { writeFileSync } from "node:fs";
11
- import { festivals } from "@nhatnguyet/le-hoi";
12
- import { renderBaZi, renderFestivals, renderLunar, renderNumerology, renderSolarTerms, renderZiWei } from "./render.js";
11
+ import { festivals, festivalsIcs } from "@nhatnguyet/le-hoi";
12
+ import { renderBaZi, renderFestivals, renderHours, renderLunar, renderNumerology, renderSolarTerms, renderZiWei } from "./render.js";
13
13
  /** Version printed by --version. */
14
- export const VERSION = "0.1.0";
14
+ export const VERSION = "0.3.0";
15
15
  export const HELP = `nhatnguyet: Zi Wei Dou Shu, BaZi, lunar calendar, numerology, Vietnamese festivals
16
16
 
17
17
  Usage:
18
- nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name "..."] [--year 2026]
19
- nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female>
18
+ nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name "..."] [--year 2026] [school options]
19
+ nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female> [--zi-hour ...]
20
20
  nhatnguyet lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]
21
21
  nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]
22
22
  nhatnguyet terms <year> [--country ...]
23
+ nhatnguyet hours <YYYY-MM-DD> auspicious and inauspicious double hours of a day
23
24
  nhatnguyet numerology "<full name>" <YYYY-MM-DD> [--today YYYY-MM-DD]
24
- nhatnguyet festivals <year>
25
+ nhatnguyet festivals <year> [--ics]
25
26
 
26
27
  Options:
27
28
  --lang en|vi|zh language of the result (default en)
29
+ --terms pinyin|han|vi English only: stems, branches and transformations as
30
+ pinyin (default, "Geng Wu"), Chinese characters or Sino-Vietnamese
28
31
  --json print JSON instead of text
29
32
  --svg <file> also write the chart as SVG (ziwei, bazi, numerology)
33
+ --ics festivals: print an iCalendar (.ics) file instead
30
34
  --theme dark dark SVG
31
35
  --no-color no ANSI colours (also when NO_COLOR is set or output is not a terminal)
36
+
37
+ School options (where the books disagree; default first, sources in docs/schools.md):
38
+ --fire-bell vietnamese|quanshu|swap-for-female|swap-for-yin-male-yang-female
39
+ --leap-month whole|split-at-15|next-month
40
+ --transformations vietnamese|quanshu|zhongzhou (Geng year row)
41
+ --heavenly-kitchen vietnamese|chinese (Gui year)
42
+ --injury-messenger standard|zhongzhou
43
+ --zi-hour next-day-from-23|split-at-midnight (bazi: day pillar from 23:00 to 24:00)
44
+
32
45
  -h, --help this help
33
46
  -v, --version version
34
47
 
35
- Times are clock times; the Tý double hour runs 23:00 to 00:59. Dates and times
48
+ Times are clock times; the Zi (Rat) double hour runs 23:00 to 00:59. Dates and times
36
49
  are read as Vietnam time (UTC+7) unless --country says otherwise (lunar, solar,
37
- terms). Docs: https://nhatnguyet.org/ma-nguon-mo`;
50
+ terms, ziwei). Docs: https://nhatnguyet.org/en/ma-nguon-mo`;
51
+ // Mọi tên công cụ MCP cũng là bí danh của lệnh tương ứng (cast_ziwei, solar_terms...).
38
52
  const ALIAS = {
39
- ziwei: "ziwei", "zi-wei": "ziwei", tuvi: "ziwei", "tu-vi": "ziwei",
40
- bazi: "bazi", "ba-zi": "bazi", battu: "bazi", "bat-tu": "bazi",
41
- lunar: "lunar", amlich: "lunar", "am-lich": "lunar",
53
+ ziwei: "ziwei", "zi-wei": "ziwei", zi_wei: "ziwei", cast_ziwei: "ziwei", cast_zi_wei: "ziwei", tuvi: "ziwei", "tu-vi": "ziwei",
54
+ bazi: "bazi", "ba-zi": "bazi", cast_bazi: "bazi", battu: "bazi", "bat-tu": "bazi",
55
+ lunar: "lunar", lunar_convert: "lunar", amlich: "lunar", "am-lich": "lunar",
42
56
  solar: "solar", duong: "solar",
43
- terms: "terms", "solar-terms": "terms", tietkhi: "terms",
57
+ terms: "terms", "solar-terms": "terms", solar_terms: "terms", tietkhi: "terms",
58
+ hours: "hours", auspicious_hours: "hours", "auspicious-hours": "hours", "gio-hoang-dao": "hours",
44
59
  numerology: "numerology", "than-so-hoc": "numerology",
45
60
  festivals: "festivals", "le-hoi": "festivals", lehoi: "festivals",
46
61
  };
62
+ // Cờ lựa chọn phái: tên cờ (kebab-case) và khoá của `schools`.
63
+ const SCHOOL_FLAGS = ["fire-bell", "leap-month", "transformations", "heavenly-kitchen", "injury-messenger", "zi-hour"];
64
+ /** Lựa chọn phái từ các cờ (chỉ những cờ có mặt); undefined khi không có cờ nào. */
65
+ function schoolsFrom(flags, keys) {
66
+ const r = {};
67
+ for (const f of keys) {
68
+ const v = flags[f];
69
+ if (v === undefined)
70
+ continue;
71
+ if (typeof v !== "string")
72
+ throw new TypeError(`--${f} needs a value`);
73
+ r[f.replace(/-(\w)/g, (_, c) => c.toUpperCase())] = v;
74
+ }
75
+ return Object.keys(r).length ? r : undefined;
76
+ }
47
77
  /** Split argv (without node and script) into command, positional arguments and flags. */
48
78
  export function parseArgs(argv) {
49
79
  const positional = [];
50
80
  const flags = {};
51
- const coGiaTri = new Set(["lang", "country", "name", "year", "today", "tz", "svg", "theme"]);
81
+ const coGiaTri = new Set(["lang", "country", "name", "year", "today", "tz", "svg", "theme", "terms", ...SCHOOL_FLAGS]);
52
82
  for (let i = 0; i < argv.length; i++) {
53
83
  const a = argv[i];
54
84
  if (a === "-h")
@@ -83,6 +113,7 @@ export function run(argv, env) {
83
113
  if (flags.help || command === "" || command === "help")
84
114
  return HELP;
85
115
  const lang = (typeof flags.lang === "string" ? flags.lang : "en");
116
+ const terms = checkTerms(typeof flags.terms === "string" ? flags.terms : undefined, lang === "vi" || lang === "zh" ? lang : "en");
86
117
  const json = flags.json === true;
87
118
  const opts = { color: env.color && flags.color !== false && flags["no-color"] !== true, width: env.width };
88
119
  const country = typeof flags.country === "string" ? flags.country : undefined;
@@ -101,7 +132,8 @@ export function run(argv, env) {
101
132
  case "ziwei": {
102
133
  can(3, "ziwei <YYYY-MM-DD> <HH:MM> <male|female>");
103
134
  const year = typeof flags.year === "string" ? Number(flags.year) : undefined;
104
- const chart = castZiWei({ date: p[0], time: p[1], gender: p[2], name: typeof flags.name === "string" ? flags.name : undefined, lang, viewYear: year });
135
+ const schools = schoolsFrom(flags, SCHOOL_FLAGS.slice(0, 5));
136
+ const chart = castZiWei({ date: p[0], time: p[1], gender: p[2], name: typeof flags.name === "string" ? flags.name : undefined, lang, terms, viewYear: year, schools, country });
105
137
  const extra = { decades: decadeLuck(chart), year: yearlyLuck(chart), patterns: findPatterns(chart) };
106
138
  ghiSvg(() => ziWeiSvg(chart, { theme }));
107
139
  if (json)
@@ -113,13 +145,13 @@ export function run(argv, env) {
113
145
  const coGio = p.length >= 3 || !GIOI.test(p[1]);
114
146
  if (coGio)
115
147
  can(3, "bazi <YYYY-MM-DD> [HH:MM] <male|female>");
116
- const chart = castBaZi({ date: p[0], time: coGio ? p[1] : null, gender: coGio ? p[2] : p[1], lang });
148
+ const chart = castBaZi({ date: p[0], time: coGio ? p[1] : null, gender: coGio ? p[2] : p[1], lang, terms, schools: schoolsFrom(flags, ["zi-hour"]) });
117
149
  ghiSvg(() => baZiSvg(chart, { theme, name: typeof flags.name === "string" ? flags.name : "" }));
118
150
  return json ? dumpJson(chart) : renderBaZi(chart, opts);
119
151
  }
120
152
  case "lunar": {
121
153
  can(1, "lunar <YYYY-MM-DD> [--country CN]");
122
- const r = toLunar(p[0], { country, lang });
154
+ const r = toLunar(p[0], { country, lang, terms });
123
155
  return json ? dumpJson(r) : renderLunar(r, opts);
124
156
  }
125
157
  case "solar": {
@@ -128,13 +160,19 @@ export function run(argv, env) {
128
160
  if (!k)
129
161
  throw new Error("lunar date must look like YYYY-MM-DD");
130
162
  const r = toSolar({ year: Number(k[1]), month: Number(k[2]), day: Number(k[3]), leap: flags.leap === true }, { country });
131
- return json ? dumpJson(r) : r.date;
163
+ // Bảng như lệnh lunar, dựng từ ngày dương vừa đổi được.
164
+ return json ? dumpJson(r) : renderLunar(toLunar(r.date, { country, lang, terms }), opts);
132
165
  }
133
166
  case "terms": {
134
167
  can(1, "terms <year>");
135
168
  const y = Number(p[0]);
136
169
  const t = solarTerms(y, { country, lang });
137
- return json ? dumpJson(t) : renderSolarTerms(y, t, lang, opts);
170
+ return json ? dumpJson(t) : renderSolarTerms(y, t, lang, opts, terms);
171
+ }
172
+ case "hours": {
173
+ can(1, "hours <YYYY-MM-DD>");
174
+ const r = auspiciousHours(p[0], { lang, terms });
175
+ return json ? dumpJson(r) : renderHours(r, opts);
138
176
  }
139
177
  case "numerology": {
140
178
  can(2, 'numerology "<full name>" <YYYY-MM-DD>');
@@ -145,6 +183,9 @@ export function run(argv, env) {
145
183
  case "festivals": {
146
184
  can(1, "festivals <year>");
147
185
  const y = Number(p[0]);
186
+ // --ics: tệp kết thúc bằng CRLF; main() thêm "\n" nên bỏ "\n" cuối ở đây.
187
+ if (flags.ics === true)
188
+ return festivalsIcs(y, { lang }).slice(0, -1);
148
189
  const list = festivals(y, { lang });
149
190
  return json ? dumpJson(list) : renderFestivals(y, list, lang, opts);
150
191
  }
@@ -157,6 +198,13 @@ function main() {
157
198
  const ep = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
158
199
  const color = env.NO_COLOR === undefined && (ep || (!!out.isTTY && env.TERM !== "dumb"));
159
200
  const width = out.isTTY && out.columns ? Math.min(out.columns, 140) : 88;
201
+ // Người đọc đóng ống sớm (`nhatnguyet festivals 2027 --ics | head`): thoát
202
+ // êm với mã 0 như lệnh Unix thường, không in lỗi EPIPE.
203
+ out.on("error", (e) => {
204
+ if (e.code === "EPIPE")
205
+ process.exit(0);
206
+ throw e;
207
+ });
160
208
  try {
161
209
  out.write(run(process.argv.slice(2), { color, width }) + "\n");
162
210
  }
package/dist/render.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { LunarResult, SolarTerm } from "@nhatnguyet/am-lich";
1
+ import type { AuspiciousHoursResult, LunarResult, SolarTerm, Terms } from "@nhatnguyet/am-lich";
2
2
  import type { ZiWeiChart, DecadeLuck, YearlyLuck, ZiWeiPattern } from "@nhatnguyet/tu-vi";
3
3
  import type { BaZiChart } from "@nhatnguyet/bat-tu";
4
4
  import type { NumerologyResult } from "@nhatnguyet/than-so-hoc";
@@ -36,8 +36,15 @@ export declare function renderZiWei(chart: ZiWeiChart, extra: {
36
36
  export declare function renderBaZi(chart: BaZiChart, opts?: RenderOptions): string;
37
37
  /** A lunar date as a small key-value box. */
38
38
  export declare function renderLunar(r: LunarResult, opts?: RenderOptions): string;
39
- /** The 24 solar terms of a year as a table. */
40
- export declare function renderSolarTerms(year: number, terms: SolarTerm[], lang: Lang, opts?: RenderOptions): string;
39
+ /**
40
+ * The 24 solar terms of a year as a table. The name is in `lang` only; in
41
+ * English, `nameTerms` "han" or "vi" adds the Chinese or Vietnamese name in
42
+ * brackets ("Minor Cold (小寒)", "Minor Cold (Tiểu Hàn)"), "pinyin" (default)
43
+ * adds nothing.
44
+ */
45
+ export declare function renderSolarTerms(year: number, terms: SolarTerm[], lang: Lang, opts?: RenderOptions, nameTerms?: Terms): string;
46
+ /** The twelve double hours of a day: branch, clock range, auspicious or not, spirit. */
47
+ export declare function renderHours(r: AuspiciousHoursResult, opts?: RenderOptions): string;
41
48
  /** Numerology numbers, the 3x3 birth-date grid, pinnacles and challenges. */
42
49
  export declare function renderNumerology(r: NumerologyResult, opts?: RenderOptions): string;
43
50
  /** Festivals of a year as a table: date, fixed date, name. */
package/dist/render.js CHANGED
@@ -3,6 +3,7 @@
3
3
  // ANSI chỉ khi người gọi bật (cli.ts tắt khi không phải TTY hay có NO_COLOR).
4
4
  //
5
5
  // Renders results of the English API as terminal text.
6
+ import { term } from "@nhatnguyet/am-lich";
6
7
  // ── Đo bề rộng hiển thị ─────────────────────────────────────────────────
7
8
  /** Terminal columns taken by one code point: 2 for CJK and fullwidth, 0 for combining marks. */
8
9
  export function charWidth(cp) {
@@ -163,6 +164,7 @@ const UI = {
163
164
  gregorian: "Dương lịch", month: "Tháng", day: "Ngày", zodiac: "Con giáp", solarTerm: "Tiết khí", country: "Lịch",
164
165
  nmTitle: "THẦN SỐ HỌC", pinnacles: "Đỉnh cao", challenges: "Thách thức", until: "tới", fest: "LỄ HỘI",
165
166
  terms: "TIẾT KHÍ", unknown: "chưa biết giờ", male: "Nam", female: "Nữ",
167
+ hrsTitle: "GIỜ HOÀNG ĐẠO", good: "hoàng đạo", bad: "hắc đạo",
166
168
  },
167
169
  en: {
168
170
  zwTitle: "ZI WEI DOU SHU CHART", body: "Body", life: "Life", tuan: "Tuần", triet: "Triệt", born: "Born", lunar: "Lunar",
@@ -175,6 +177,7 @@ const UI = {
175
177
  gregorian: "Gregorian", month: "Month", day: "Day", zodiac: "Zodiac", solarTerm: "Solar term", country: "Calendar",
176
178
  nmTitle: "NUMEROLOGY", pinnacles: "Pinnacles", challenges: "Challenges", until: "to age", fest: "FESTIVALS",
177
179
  terms: "SOLAR TERMS", unknown: "time unknown", male: "male", female: "female",
180
+ hrsTitle: "AUSPICIOUS HOURS", good: "auspicious", bad: "inauspicious",
178
181
  },
179
182
  zh: {
180
183
  zwTitle: "紫微斗数命盘", body: "身", life: "命", tuan: "旬空", triet: "截空", born: "出生", lunar: "农历",
@@ -187,6 +190,7 @@ const UI = {
187
190
  gregorian: "公历", month: "月", day: "日", zodiac: "生肖", solarTerm: "节气", country: "历法",
188
191
  nmTitle: "生命灵数", pinnacles: "巅峰数", challenges: "挑战数", until: "至", fest: "节日",
189
192
  terms: "二十四节气", unknown: "时辰未知", male: "男", female: "女",
193
+ hrsTitle: "黄道吉时", good: "黄道", bad: "黑道",
190
194
  },
191
195
  };
192
196
  function ui(lang) {
@@ -200,16 +204,22 @@ function doSangNgan(b, lang) {
200
204
  return b.charAt(0);
201
205
  return b.slice(0, 2);
202
206
  }
203
- /** Viết tắt Tứ Hóa: bỏ chữ "Hóa" (zh bỏ chữ 化). */
207
+ /** Viết tắt Tứ Hóa: bỏ chữ "Hóa", "Hua" hay 化 ("Hua Ji" ra "Ji", 化忌 ra 忌). */
204
208
  function hoaNgan(t, lang) {
205
- return lang === "zh" ? t.replace("化", "") : t.replace(/^Hóa\s+/, "");
209
+ return lang === "zh" || t.startsWith("化") ? t.replace("化", "") : t.replace(/^(?:Hóa|Hua)\s+/, "");
210
+ }
211
+ /** Tuần, Triệt theo cách viết của lá số (bản Anh: pinyin, chữ Hán hay Hán Việt). */
212
+ function chuKhong(chart, u) {
213
+ if (chart.lang !== "en" || chart.terms === "vi")
214
+ return [u.tuan, u.triet];
215
+ return chart.terms === "han" ? ["旬空", "截空"] : ["Xun Kong", "Jie Kong"];
206
216
  }
207
217
  // ── Lưới Tử Vi ──────────────────────────────────────────────────────────
208
218
  /** Vị trí 12 cung trên lưới 4x4 (hàng, cột), chi 0 Tý tới 11 Hợi, Tỵ ở góc trên trái. */
209
219
  const VI_TRI_LUOI = [
210
220
  [3, 2], [3, 1], [3, 0], [2, 0], [1, 0], [0, 0], [0, 1], [0, 2], [0, 3], [1, 3], [2, 3], [3, 3],
211
221
  ];
212
- function dongCung(p, lang, W) {
222
+ function dongCung(p, lang, W, khong) {
213
223
  const u = ui(lang);
214
224
  const lines = [];
215
225
  const dau = [[p.name, p.isLife ? "title" : "bold"]];
@@ -218,9 +228,9 @@ function dongCung(p, lang, W) {
218
228
  lines.push(dau);
219
229
  const dau2 = [[p.stemBranch, "dim"]];
220
230
  if (p.tuan)
221
- dau2.push([" " + u.tuan, "blue"]);
231
+ dau2.push([" " + khong[0], "blue"]);
222
232
  if (p.triet)
223
- dau2.push([" " + u.triet, "blue"]);
233
+ dau2.push([" " + khong[1], "blue"]);
224
234
  lines.push(dau2);
225
235
  for (const s of p.stars) {
226
236
  if (s.kind !== "major")
@@ -264,7 +274,7 @@ export function renderZiWeiGrid(chart, opts = {}) {
264
274
  o[r] = [[], [], [], []];
265
275
  for (const p of chart.palaces) {
266
276
  const [r, c] = VI_TRI_LUOI[p.index];
267
- o[r][c] = dongCung(p, lang, W - 2);
277
+ o[r][c] = dongCung(p, lang, W - 2, chuKhong(chart, u));
268
278
  }
269
279
  const h = [0, 0, 0, 0];
270
280
  for (let r = 0; r < 4; r++)
@@ -426,13 +436,26 @@ export function renderLunar(r, opts = {}) {
426
436
  ];
427
437
  return bang(null, rows, color);
428
438
  }
429
- /** The 24 solar terms of a year as a table. */
430
- export function renderSolarTerms(year, terms, lang, opts = {}) {
439
+ /**
440
+ * The 24 solar terms of a year as a table. The name is in `lang` only; in
441
+ * English, `nameTerms` "han" or "vi" adds the Chinese or Vietnamese name in
442
+ * brackets ("Minor Cold (小寒)", "Minor Cold (Tiểu Hàn)"), "pinyin" (default)
443
+ * adds nothing.
444
+ */
445
+ export function renderSolarTerms(year, terms, lang, opts = {}, nameTerms = "pinyin") {
431
446
  const color = opts.color === true;
432
447
  const u = ui(lang);
433
- const rows = terms.map((t) => [[t.date], [t.time], [t.name + (lang === "vi" ? "" : ` (${t.nameVi})`)], [String(t.longitude) + "°"]]);
448
+ const kem = (t) => (lang !== "en" || nameTerms === "pinyin" ? "" : ` (${nameTerms === "vi" ? t.nameVi : term(t.nameVi, "zh")})`);
449
+ const rows = terms.map((t) => [[t.date], [t.time], [t.name + kem(t)], [String(t.longitude) + "°"]]);
434
450
  return paint(`${u.terms} ${year}`, "title", color) + "\n" + bang(null, rows, color);
435
451
  }
452
+ /** The twelve double hours of a day: branch, clock range, auspicious or not, spirit. */
453
+ export function renderHours(r, opts = {}) {
454
+ const color = opts.color === true;
455
+ const u = ui(r.lang);
456
+ const rows = r.hours.map((h) => [[`${h.branch} (${h.animal})`], [h.range], [h.auspicious ? u.good : u.bad], [h.spirit]]);
457
+ return paint(u.hrsTitle, "title", color) + ` ${r.date} · ${u.day} ${r.day}` + "\n" + bang(null, rows, color);
458
+ }
436
459
  // ── Thần số học ─────────────────────────────────────────────────────────
437
460
  /** Numerology numbers, the 3x3 birth-date grid, pinnacles and challenges. */
438
461
  export function renderNumerology(r, opts = {}) {
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@nhatnguyet/cli",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Command line for Nhat Nguyet: Zi Wei Dou Shu chart as a 4x4 grid, BaZi, Vietnamese/Chinese/Korean/Japanese lunar calendar, numerology, Vietnamese festivals. English, Vietnamese, Chinese. Nhat Nguyet (nhatnguyet.org)",
5
5
  "license": "MIT",
6
6
  "author": "Nhat Nguyet (https://nhatnguyet.org)",
7
- "homepage": "https://nhatnguyet.org/ma-nguon-mo",
7
+ "homepage": "https://nhatnguyet.org/en/ma-nguon-mo",
8
8
  "keywords": [
9
9
  "cli",
10
10
  "zi wei dou shu",
@@ -41,11 +41,11 @@
41
41
  "test": "node --conditions=source --test \"test/**/*.test.ts\""
42
42
  },
43
43
  "dependencies": {
44
- "@nhatnguyet/am-lich": "^0.2.0",
45
- "@nhatnguyet/bat-tu": "^0.2.0",
46
- "@nhatnguyet/le-hoi": "^0.2.0",
47
- "@nhatnguyet/than-so-hoc": "^0.2.0",
48
- "@nhatnguyet/tu-vi": "^0.2.0"
44
+ "@nhatnguyet/am-lich": "^0.3.0",
45
+ "@nhatnguyet/bat-tu": "^0.3.0",
46
+ "@nhatnguyet/le-hoi": "^0.3.0",
47
+ "@nhatnguyet/than-so-hoc": "^0.3.0",
48
+ "@nhatnguyet/tu-vi": "^0.3.0"
49
49
  },
50
50
  "devDependencies": {
51
51
  "typescript": "^5.9.3"
package/src/cli.ts CHANGED
@@ -4,61 +4,97 @@
4
4
  //
5
5
  // Command line for the Nhat Nguyet libraries.
6
6
 
7
- import { solarTerms, toLunar, toSolar } from "@nhatnguyet/am-lich";
8
- import type { Lang } from "@nhatnguyet/am-lich";
7
+ import { auspiciousHours, checkTerms, solarTerms, toLunar, toSolar } from "@nhatnguyet/am-lich";
8
+ import type { Lang, Terms } from "@nhatnguyet/am-lich";
9
9
  import { castZiWei, decadeLuck, findPatterns, yearlyLuck, ziWeiSvg } from "@nhatnguyet/tu-vi";
10
10
  import { baZiSvg, castBaZi } from "@nhatnguyet/bat-tu";
11
11
  import { numerology, numerologySvg } from "@nhatnguyet/than-so-hoc";
12
12
  import { writeFileSync } from "node:fs";
13
- import { festivals } from "@nhatnguyet/le-hoi";
14
- import { renderBaZi, renderFestivals, renderLunar, renderNumerology, renderSolarTerms, renderZiWei } from "./render.ts";
13
+ import { festivals, festivalsIcs } from "@nhatnguyet/le-hoi";
14
+ import { renderBaZi, renderFestivals, renderHours, renderLunar, renderNumerology, renderSolarTerms, renderZiWei } from "./render.ts";
15
15
 
16
16
  // Gói không phụ thuộc @types/node: khai đúng phần process đang dùng.
17
17
  declare const process: {
18
18
  argv: string[];
19
19
  env: Record<string, string | undefined>;
20
- stdout: { isTTY?: boolean; columns?: number; write(s: string): boolean };
20
+ stdout: {
21
+ isTTY?: boolean;
22
+ columns?: number;
23
+ write(s: string): boolean;
24
+ on(ev: "error", f: (e: { code?: string }) => void): unknown;
25
+ };
21
26
  stderr: { write(s: string): boolean };
22
27
  exitCode?: number;
28
+ exit(code?: number): never;
23
29
  };
24
30
 
25
31
  /** Version printed by --version. */
26
- export const VERSION = "0.1.0";
32
+ export const VERSION = "0.3.0";
27
33
 
28
34
  export const HELP = `nhatnguyet: Zi Wei Dou Shu, BaZi, lunar calendar, numerology, Vietnamese festivals
29
35
 
30
36
  Usage:
31
- nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name "..."] [--year 2026]
32
- nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female>
37
+ nhatnguyet ziwei <YYYY-MM-DD> <HH:MM> <male|female> [--name "..."] [--year 2026] [school options]
38
+ nhatnguyet bazi <YYYY-MM-DD> [HH:MM] <male|female> [--zi-hour ...]
33
39
  nhatnguyet lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]
34
40
  nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]
35
41
  nhatnguyet terms <year> [--country ...]
42
+ nhatnguyet hours <YYYY-MM-DD> auspicious and inauspicious double hours of a day
36
43
  nhatnguyet numerology "<full name>" <YYYY-MM-DD> [--today YYYY-MM-DD]
37
- nhatnguyet festivals <year>
44
+ nhatnguyet festivals <year> [--ics]
38
45
 
39
46
  Options:
40
47
  --lang en|vi|zh language of the result (default en)
48
+ --terms pinyin|han|vi English only: stems, branches and transformations as
49
+ pinyin (default, "Geng Wu"), Chinese characters or Sino-Vietnamese
41
50
  --json print JSON instead of text
42
51
  --svg <file> also write the chart as SVG (ziwei, bazi, numerology)
52
+ --ics festivals: print an iCalendar (.ics) file instead
43
53
  --theme dark dark SVG
44
54
  --no-color no ANSI colours (also when NO_COLOR is set or output is not a terminal)
55
+
56
+ School options (where the books disagree; default first, sources in docs/schools.md):
57
+ --fire-bell vietnamese|quanshu|swap-for-female|swap-for-yin-male-yang-female
58
+ --leap-month whole|split-at-15|next-month
59
+ --transformations vietnamese|quanshu|zhongzhou (Geng year row)
60
+ --heavenly-kitchen vietnamese|chinese (Gui year)
61
+ --injury-messenger standard|zhongzhou
62
+ --zi-hour next-day-from-23|split-at-midnight (bazi: day pillar from 23:00 to 24:00)
63
+
45
64
  -h, --help this help
46
65
  -v, --version version
47
66
 
48
- Times are clock times; the Tý double hour runs 23:00 to 00:59. Dates and times
67
+ Times are clock times; the Zi (Rat) double hour runs 23:00 to 00:59. Dates and times
49
68
  are read as Vietnam time (UTC+7) unless --country says otherwise (lunar, solar,
50
- terms). Docs: https://nhatnguyet.org/ma-nguon-mo`;
69
+ terms, ziwei). Docs: https://nhatnguyet.org/en/ma-nguon-mo`;
51
70
 
71
+ // Mọi tên công cụ MCP cũng là bí danh của lệnh tương ứng (cast_ziwei, solar_terms...).
52
72
  const ALIAS: Readonly<Record<string, string>> = {
53
- ziwei: "ziwei", "zi-wei": "ziwei", tuvi: "ziwei", "tu-vi": "ziwei",
54
- bazi: "bazi", "ba-zi": "bazi", battu: "bazi", "bat-tu": "bazi",
55
- lunar: "lunar", amlich: "lunar", "am-lich": "lunar",
73
+ ziwei: "ziwei", "zi-wei": "ziwei", zi_wei: "ziwei", cast_ziwei: "ziwei", cast_zi_wei: "ziwei", tuvi: "ziwei", "tu-vi": "ziwei",
74
+ bazi: "bazi", "ba-zi": "bazi", cast_bazi: "bazi", battu: "bazi", "bat-tu": "bazi",
75
+ lunar: "lunar", lunar_convert: "lunar", amlich: "lunar", "am-lich": "lunar",
56
76
  solar: "solar", duong: "solar",
57
- terms: "terms", "solar-terms": "terms", tietkhi: "terms",
77
+ terms: "terms", "solar-terms": "terms", solar_terms: "terms", tietkhi: "terms",
78
+ hours: "hours", auspicious_hours: "hours", "auspicious-hours": "hours", "gio-hoang-dao": "hours",
58
79
  numerology: "numerology", "than-so-hoc": "numerology",
59
80
  festivals: "festivals", "le-hoi": "festivals", lehoi: "festivals",
60
81
  };
61
82
 
83
+ // Cờ lựa chọn phái: tên cờ (kebab-case) và khoá của `schools`.
84
+ const SCHOOL_FLAGS = ["fire-bell", "leap-month", "transformations", "heavenly-kitchen", "injury-messenger", "zi-hour"];
85
+
86
+ /** Lựa chọn phái từ các cờ (chỉ những cờ có mặt); undefined khi không có cờ nào. */
87
+ function schoolsFrom(flags: Record<string, string | boolean>, keys: string[]): Record<string, string> | undefined {
88
+ const r: Record<string, string> = {};
89
+ for (const f of keys) {
90
+ const v = flags[f];
91
+ if (v === undefined) continue;
92
+ if (typeof v !== "string") throw new TypeError(`--${f} needs a value`);
93
+ r[f.replace(/-(\w)/g, (_, c: string) => c.toUpperCase())] = v;
94
+ }
95
+ return Object.keys(r).length ? r : undefined;
96
+ }
97
+
62
98
  /** Parsed command line. */
63
99
  export interface Args {
64
100
  command: string;
@@ -70,7 +106,7 @@ export interface Args {
70
106
  export function parseArgs(argv: string[]): Args {
71
107
  const positional: string[] = [];
72
108
  const flags: Record<string, string | boolean> = {};
73
- const coGiaTri = new Set(["lang", "country", "name", "year", "today", "tz", "svg", "theme"]);
109
+ const coGiaTri = new Set(["lang", "country", "name", "year", "today", "tz", "svg", "theme", "terms", ...SCHOOL_FLAGS]);
74
110
  for (let i = 0; i < argv.length; i++) {
75
111
  const a = argv[i];
76
112
  if (a === "-h") flags.help = true;
@@ -104,6 +140,7 @@ export function run(argv: string[], env: RunEnv): string {
104
140
  if (flags.version) return VERSION;
105
141
  if (flags.help || command === "" || command === "help") return HELP;
106
142
  const lang = (typeof flags.lang === "string" ? flags.lang : "en") as Lang;
143
+ const terms: Terms = checkTerms(typeof flags.terms === "string" ? flags.terms : undefined, lang === "vi" || lang === "zh" ? lang : "en");
107
144
  const json = flags.json === true;
108
145
  const opts = { color: env.color && flags.color !== false && flags["no-color"] !== true, width: env.width };
109
146
  const country = typeof flags.country === "string" ? flags.country : undefined;
@@ -121,7 +158,8 @@ export function run(argv: string[], env: RunEnv): string {
121
158
  case "ziwei": {
122
159
  can(3, "ziwei <YYYY-MM-DD> <HH:MM> <male|female>");
123
160
  const year = typeof flags.year === "string" ? Number(flags.year) : undefined;
124
- const chart = castZiWei({ date: p[0], time: p[1], gender: p[2], name: typeof flags.name === "string" ? flags.name : undefined, lang, viewYear: year });
161
+ const schools = schoolsFrom(flags, SCHOOL_FLAGS.slice(0, 5));
162
+ const chart = castZiWei({ date: p[0], time: p[1], gender: p[2], name: typeof flags.name === "string" ? flags.name : undefined, lang, terms, viewYear: year, schools, country });
125
163
  const extra = { decades: decadeLuck(chart), year: yearlyLuck(chart), patterns: findPatterns(chart) };
126
164
  ghiSvg(() => ziWeiSvg(chart, { theme }));
127
165
  if (json) return dumpJson({ chart, ...extra });
@@ -131,13 +169,13 @@ export function run(argv: string[], env: RunEnv): string {
131
169
  can(2, "bazi <YYYY-MM-DD> [HH:MM] <male|female>");
132
170
  const coGio = p.length >= 3 || !GIOI.test(p[1]);
133
171
  if (coGio) can(3, "bazi <YYYY-MM-DD> [HH:MM] <male|female>");
134
- const chart = castBaZi({ date: p[0], time: coGio ? p[1] : null, gender: coGio ? p[2] : p[1], lang });
172
+ const chart = castBaZi({ date: p[0], time: coGio ? p[1] : null, gender: coGio ? p[2] : p[1], lang, terms, schools: schoolsFrom(flags, ["zi-hour"]) });
135
173
  ghiSvg(() => baZiSvg(chart, { theme, name: typeof flags.name === "string" ? flags.name : "" }));
136
174
  return json ? dumpJson(chart) : renderBaZi(chart, opts);
137
175
  }
138
176
  case "lunar": {
139
177
  can(1, "lunar <YYYY-MM-DD> [--country CN]");
140
- const r = toLunar(p[0], { country, lang });
178
+ const r = toLunar(p[0], { country, lang, terms });
141
179
  return json ? dumpJson(r) : renderLunar(r, opts);
142
180
  }
143
181
  case "solar": {
@@ -145,13 +183,19 @@ export function run(argv: string[], env: RunEnv): string {
145
183
  const k = /^(-?\d+)-(\d+)-(\d+)$/.exec(p[0]);
146
184
  if (!k) throw new Error("lunar date must look like YYYY-MM-DD");
147
185
  const r = toSolar({ year: Number(k[1]), month: Number(k[2]), day: Number(k[3]), leap: flags.leap === true }, { country });
148
- return json ? dumpJson(r) : r.date;
186
+ // Bảng như lệnh lunar, dựng từ ngày dương vừa đổi được.
187
+ return json ? dumpJson(r) : renderLunar(toLunar(r.date, { country, lang, terms }), opts);
149
188
  }
150
189
  case "terms": {
151
190
  can(1, "terms <year>");
152
191
  const y = Number(p[0]);
153
192
  const t = solarTerms(y, { country, lang });
154
- return json ? dumpJson(t) : renderSolarTerms(y, t, lang, opts);
193
+ return json ? dumpJson(t) : renderSolarTerms(y, t, lang, opts, terms);
194
+ }
195
+ case "hours": {
196
+ can(1, "hours <YYYY-MM-DD>");
197
+ const r = auspiciousHours(p[0], { lang, terms });
198
+ return json ? dumpJson(r) : renderHours(r, opts);
155
199
  }
156
200
  case "numerology": {
157
201
  can(2, 'numerology "<full name>" <YYYY-MM-DD>');
@@ -162,6 +206,8 @@ export function run(argv: string[], env: RunEnv): string {
162
206
  case "festivals": {
163
207
  can(1, "festivals <year>");
164
208
  const y = Number(p[0]);
209
+ // --ics: tệp kết thúc bằng CRLF; main() thêm "\n" nên bỏ "\n" cuối ở đây.
210
+ if (flags.ics === true) return festivalsIcs(y, { lang }).slice(0, -1);
165
211
  const list = festivals(y, { lang });
166
212
  return json ? dumpJson(list) : renderFestivals(y, list, lang, opts);
167
213
  }
@@ -175,6 +221,12 @@ function main(): void {
175
221
  const ep = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
176
222
  const color = env.NO_COLOR === undefined && (ep || (!!out.isTTY && env.TERM !== "dumb"));
177
223
  const width = out.isTTY && out.columns ? Math.min(out.columns, 140) : 88;
224
+ // Người đọc đóng ống sớm (`nhatnguyet festivals 2027 --ics | head`): thoát
225
+ // êm với mã 0 như lệnh Unix thường, không in lỗi EPIPE.
226
+ out.on("error", (e) => {
227
+ if (e.code === "EPIPE") process.exit(0);
228
+ throw e;
229
+ });
178
230
  try {
179
231
  out.write(run(process.argv.slice(2), { color, width }) + "\n");
180
232
  } catch (e) {
package/src/render.ts CHANGED
@@ -4,7 +4,8 @@
4
4
  //
5
5
  // Renders results of the English API as terminal text.
6
6
 
7
- import type { LunarResult, SolarTerm } from "@nhatnguyet/am-lich";
7
+ import { term } from "@nhatnguyet/am-lich";
8
+ import type { AuspiciousHoursResult, LunarResult, SolarTerm, Terms } from "@nhatnguyet/am-lich";
8
9
  import type { ZiWeiChart, ZiWeiPalace, DecadeLuck, YearlyLuck, ZiWeiPattern } from "@nhatnguyet/tu-vi";
9
10
  import type { BaZiChart, BaZiPillar } from "@nhatnguyet/bat-tu";
10
11
  import type { NumerologyResult } from "@nhatnguyet/than-so-hoc";
@@ -187,6 +188,7 @@ const UI: Readonly<Record<Lang, Readonly<Record<string, string>>>> = {
187
188
  gregorian: "Dương lịch", month: "Tháng", day: "Ngày", zodiac: "Con giáp", solarTerm: "Tiết khí", country: "Lịch",
188
189
  nmTitle: "THẦN SỐ HỌC", pinnacles: "Đỉnh cao", challenges: "Thách thức", until: "tới", fest: "LỄ HỘI",
189
190
  terms: "TIẾT KHÍ", unknown: "chưa biết giờ", male: "Nam", female: "Nữ",
191
+ hrsTitle: "GIỜ HOÀNG ĐẠO", good: "hoàng đạo", bad: "hắc đạo",
190
192
  },
191
193
  en: {
192
194
  zwTitle: "ZI WEI DOU SHU CHART", body: "Body", life: "Life", tuan: "Tuần", triet: "Triệt", born: "Born", lunar: "Lunar",
@@ -199,6 +201,7 @@ const UI: Readonly<Record<Lang, Readonly<Record<string, string>>>> = {
199
201
  gregorian: "Gregorian", month: "Month", day: "Day", zodiac: "Zodiac", solarTerm: "Solar term", country: "Calendar",
200
202
  nmTitle: "NUMEROLOGY", pinnacles: "Pinnacles", challenges: "Challenges", until: "to age", fest: "FESTIVALS",
201
203
  terms: "SOLAR TERMS", unknown: "time unknown", male: "male", female: "female",
204
+ hrsTitle: "AUSPICIOUS HOURS", good: "auspicious", bad: "inauspicious",
202
205
  },
203
206
  zh: {
204
207
  zwTitle: "紫微斗数命盘", body: "身", life: "命", tuan: "旬空", triet: "截空", born: "出生", lunar: "农历",
@@ -211,6 +214,7 @@ const UI: Readonly<Record<Lang, Readonly<Record<string, string>>>> = {
211
214
  gregorian: "公历", month: "月", day: "日", zodiac: "生肖", solarTerm: "节气", country: "历法",
212
215
  nmTitle: "生命灵数", pinnacles: "巅峰数", challenges: "挑战数", until: "至", fest: "节日",
213
216
  terms: "二十四节气", unknown: "时辰未知", male: "男", female: "女",
217
+ hrsTitle: "黄道吉时", good: "黄道", bad: "黑道",
214
218
  },
215
219
  };
216
220
 
@@ -225,9 +229,15 @@ function doSangNgan(b: string, lang: Lang): string {
225
229
  return b.slice(0, 2);
226
230
  }
227
231
 
228
- /** Viết tắt Tứ Hóa: bỏ chữ "Hóa" (zh bỏ chữ 化). */
232
+ /** Viết tắt Tứ Hóa: bỏ chữ "Hóa", "Hua" hay 化 ("Hua Ji" ra "Ji", 化忌 ra 忌). */
229
233
  function hoaNgan(t: string, lang: Lang): string {
230
- return lang === "zh" ? t.replace("化", "") : t.replace(/^Hóa\s+/, "");
234
+ return lang === "zh" || t.startsWith("化") ? t.replace("化", "") : t.replace(/^(?:Hóa|Hua)\s+/, "");
235
+ }
236
+
237
+ /** Tuần, Triệt theo cách viết của lá số (bản Anh: pinyin, chữ Hán hay Hán Việt). */
238
+ function chuKhong(chart: ZiWeiChart, u: Readonly<Record<string, string>>): [string, string] {
239
+ if (chart.lang !== "en" || chart.terms === "vi") return [u.tuan, u.triet];
240
+ return chart.terms === "han" ? ["旬空", "截空"] : ["Xun Kong", "Jie Kong"];
231
241
  }
232
242
 
233
243
  // ── Lưới Tử Vi ──────────────────────────────────────────────────────────
@@ -237,15 +247,15 @@ const VI_TRI_LUOI: ReadonlyArray<readonly [number, number]> = [
237
247
  [3, 2], [3, 1], [3, 0], [2, 0], [1, 0], [0, 0], [0, 1], [0, 2], [0, 3], [1, 3], [2, 3], [3, 3],
238
248
  ];
239
249
 
240
- function dongCung(p: ZiWeiPalace, lang: Lang, W: number): Line[] {
250
+ function dongCung(p: ZiWeiPalace, lang: Lang, W: number, khong: [string, string]): Line[] {
241
251
  const u = ui(lang);
242
252
  const lines: Line[] = [];
243
253
  const dau: Line = [[p.name, p.isLife ? "title" : "bold"]];
244
254
  if (p.isBody) dau.push([" · " + u.body, "yellow"]);
245
255
  lines.push(dau);
246
256
  const dau2: Line = [[p.stemBranch, "dim"]];
247
- if (p.tuan) dau2.push([" " + u.tuan, "blue"]);
248
- if (p.triet) dau2.push([" " + u.triet, "blue"]);
257
+ if (p.tuan) dau2.push([" " + khong[0], "blue"]);
258
+ if (p.triet) dau2.push([" " + khong[1], "blue"]);
249
259
  lines.push(dau2);
250
260
  for (const s of p.stars) {
251
261
  if (s.kind !== "major") continue;
@@ -282,7 +292,7 @@ export function renderZiWeiGrid(chart: ZiWeiChart, opts: RenderOptions = {}): st
282
292
  for (let r = 0; r < 4; r++) o[r] = [[], [], [], []];
283
293
  for (const p of chart.palaces) {
284
294
  const [r, c] = VI_TRI_LUOI[p.index];
285
- o[r][c] = dongCung(p, lang, W - 2);
295
+ o[r][c] = dongCung(p, lang, W - 2, chuKhong(chart, u));
286
296
  }
287
297
  const h = [0, 0, 0, 0];
288
298
  for (let r = 0; r < 4; r++) for (let c = 0; c < 4; c++) h[r] = Math.max(h[r], o[r][c].length);
@@ -448,14 +458,28 @@ export function renderLunar(r: LunarResult, opts: RenderOptions = {}): string {
448
458
  return bang(null, rows, color);
449
459
  }
450
460
 
451
- /** The 24 solar terms of a year as a table. */
452
- export function renderSolarTerms(year: number, terms: SolarTerm[], lang: Lang, opts: RenderOptions = {}): string {
461
+ /**
462
+ * The 24 solar terms of a year as a table. The name is in `lang` only; in
463
+ * English, `nameTerms` "han" or "vi" adds the Chinese or Vietnamese name in
464
+ * brackets ("Minor Cold (小寒)", "Minor Cold (Tiểu Hàn)"), "pinyin" (default)
465
+ * adds nothing.
466
+ */
467
+ export function renderSolarTerms(year: number, terms: SolarTerm[], lang: Lang, opts: RenderOptions = {}, nameTerms: Terms = "pinyin"): string {
453
468
  const color = opts.color === true;
454
469
  const u = ui(lang);
455
- const rows = terms.map((t) => [[t.date], [t.time], [t.name + (lang === "vi" ? "" : ` (${t.nameVi})`)], [String(t.longitude) + "°"]]);
470
+ const kem = (t: SolarTerm) => (lang !== "en" || nameTerms === "pinyin" ? "" : ` (${nameTerms === "vi" ? t.nameVi : term(t.nameVi, "zh")})`);
471
+ const rows = terms.map((t) => [[t.date], [t.time], [t.name + kem(t)], [String(t.longitude) + "°"]]);
456
472
  return paint(`${u.terms} ${year}`, "title", color) + "\n" + bang(null, rows, color);
457
473
  }
458
474
 
475
+ /** The twelve double hours of a day: branch, clock range, auspicious or not, spirit. */
476
+ export function renderHours(r: AuspiciousHoursResult, opts: RenderOptions = {}): string {
477
+ const color = opts.color === true;
478
+ const u = ui(r.lang);
479
+ const rows = r.hours.map((h) => [[`${h.branch} (${h.animal})`], [h.range], [h.auspicious ? u.good : u.bad], [h.spirit]]);
480
+ return paint(u.hrsTitle, "title", color) + ` ${r.date} · ${u.day} ${r.day}` + "\n" + bang(null, rows, color);
481
+ }
482
+
459
483
  // ── Thần số học ─────────────────────────────────────────────────────────
460
484
 
461
485
  /** Numerology numbers, the 3x3 birth-date grid, pinnacles and challenges. */