@nhatnguyet/cli 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nhat Nguyet (nhatnguyet.org)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,77 @@
1
- # Temporary Holding Version
1
+ # @nhatnguyet/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Zi Wei Dou Shu, BaZi, numerology and the Vietnamese, Chinese, Korean and
4
+ Japanese lunar calendars in your terminal.** Charts print as grids, or as JSON
5
+ and SVG. English by default, Vietnamese and Chinese with `--lang`. Runs
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.
8
+
9
+ ```bash
10
+ npx @nhatnguyet/cli lunar 1985-01-21 --country CN
11
+ ```
12
+
13
+ ```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
+ └────────────┴───────────────┘
23
+ ```
24
+
25
+ Without `--country CN` the same day is Tết, `1985-01-01`, on the Vietnamese
26
+ calendar (UTC+7).
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ npm i -g @nhatnguyet/cli # then: nhatnguyet ...
32
+ ```
33
+
34
+ Node.js 18 or newer. The Python package prints the same text:
35
+ `pip install nhatnguyet`, then `nhatnguyet ...` or `python -m nhatnguyet ...`.
36
+
37
+ ## Commands
38
+
39
+ ```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 lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]
43
+ nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]
44
+ nhatnguyet terms <year> [--country ...]
45
+ nhatnguyet numerology "<full name>" <YYYY-MM-DD> [--today YYYY-MM-DD]
46
+ nhatnguyet festivals <year>
47
+ ```
48
+
49
+ | Option | Meaning |
50
+ |---|---|
51
+ | `--lang en\|vi\|zh` | language of the result (default `en`) |
52
+ | `--json` | print JSON instead of text |
53
+ | `--svg <file>` | also write the chart as SVG (`ziwei`, `bazi`, `numerology`) |
54
+ | `--theme dark` | dark SVG |
55
+ | `--no-color` | no ANSI colours (also when `NO_COLOR` is set or output is not a terminal) |
56
+
57
+ Times are clock times; the Tý double hour runs 23:00 to 00:59. Dates and times
58
+ are read as Vietnam time (UTC+7) unless `--country` says otherwise.
59
+
60
+ ```bash
61
+ nhatnguyet ziwei 1990-09-19 20:00 male --year 2026 # 12-palace grid, ten-year periods, patterns
62
+ nhatnguyet bazi 1990-09-19 female # birth time unknown: three pillars
63
+ nhatnguyet solar 2023-02-01 --leap # 2023-03-22
64
+ nhatnguyet numerology "Nguyen Van An" 1990-09-19 --today 2026-11-19
65
+ nhatnguyet ziwei 1990-09-19 20:00 male --svg chart.svg --theme dark
66
+ ```
67
+
68
+ A full `ziwei` output is in the
69
+ [repository README](https://github.com/Nhat-Nguyet/nhatnguyet-lunar-ziwei-bazi-numerology#quick-start).
70
+ For AI assistants, the same calculations are available as an MCP server:
71
+ [`@nhatnguyet/mcp`](https://www.npmjs.com/package/@nhatnguyet/mcp).
72
+
73
+ ## License
74
+
75
+ MIT. Please credit `Data: Nhat Nguyet (nhatnguyet.org)` when you show results
76
+ to users. Zi Wei Dou Shu, BaZi and numerology are traditional systems, not
77
+ validated science.
package/dist/cli.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
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";
5
+ /** Parsed command line. */
6
+ export interface Args {
7
+ command: string;
8
+ positional: string[];
9
+ flags: Record<string, string | boolean>;
10
+ }
11
+ /** Split argv (without node and script) into command, positional arguments and flags. */
12
+ export declare function parseArgs(argv: string[]): Args;
13
+ /** Where `run` writes files (the SVG of --svg); tests pass their own. */
14
+ export interface RunEnv {
15
+ color: boolean;
16
+ width: number;
17
+ writeFile?: (path: string, data: string) => void;
18
+ }
19
+ /** Run one command; returns the text to print (no trailing newline). */
20
+ export declare function run(argv: string[], env: RunEnv): string;
package/dist/cli.js ADDED
@@ -0,0 +1,174 @@
1
+ #!/usr/bin/env node
2
+ // Lệnh dòng lệnh `nhatnguyet`: gọi lớp API tiếng Anh của các gói @nhatnguyet
3
+ // rồi in ra terminal (render.ts) hoặc JSON (--json).
4
+ //
5
+ // Command line for the Nhat Nguyet libraries.
6
+ import { solarTerms, toLunar, toSolar } from "@nhatnguyet/am-lich";
7
+ import { castZiWei, decadeLuck, findPatterns, yearlyLuck, ziWeiSvg } from "@nhatnguyet/tu-vi";
8
+ import { baZiSvg, castBaZi } from "@nhatnguyet/bat-tu";
9
+ import { numerology, numerologySvg } from "@nhatnguyet/than-so-hoc";
10
+ import { writeFileSync } from "node:fs";
11
+ import { festivals } from "@nhatnguyet/le-hoi";
12
+ import { renderBaZi, renderFestivals, renderLunar, renderNumerology, renderSolarTerms, renderZiWei } from "./render.js";
13
+ /** Version printed by --version. */
14
+ export const VERSION = "0.1.0";
15
+ export const HELP = `nhatnguyet: Zi Wei Dou Shu, BaZi, lunar calendar, numerology, Vietnamese festivals
16
+
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>
20
+ nhatnguyet lunar <YYYY-MM-DD> [--country VN|CN|KR|JP|...]
21
+ nhatnguyet solar <lunar YYYY-MM-DD> [--leap] [--country ...]
22
+ nhatnguyet terms <year> [--country ...]
23
+ nhatnguyet numerology "<full name>" <YYYY-MM-DD> [--today YYYY-MM-DD]
24
+ nhatnguyet festivals <year>
25
+
26
+ Options:
27
+ --lang en|vi|zh language of the result (default en)
28
+ --json print JSON instead of text
29
+ --svg <file> also write the chart as SVG (ziwei, bazi, numerology)
30
+ --theme dark dark SVG
31
+ --no-color no ANSI colours (also when NO_COLOR is set or output is not a terminal)
32
+ -h, --help this help
33
+ -v, --version version
34
+
35
+ Times are clock times; the Tý double hour runs 23:00 to 00:59. Dates and times
36
+ are read as Vietnam time (UTC+7) unless --country says otherwise (lunar, solar,
37
+ terms). Docs: https://nhatnguyet.org/ma-nguon-mo`;
38
+ 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",
42
+ solar: "solar", duong: "solar",
43
+ terms: "terms", "solar-terms": "terms", tietkhi: "terms",
44
+ numerology: "numerology", "than-so-hoc": "numerology",
45
+ festivals: "festivals", "le-hoi": "festivals", lehoi: "festivals",
46
+ };
47
+ /** Split argv (without node and script) into command, positional arguments and flags. */
48
+ export function parseArgs(argv) {
49
+ const positional = [];
50
+ const flags = {};
51
+ const coGiaTri = new Set(["lang", "country", "name", "year", "today", "tz", "svg", "theme"]);
52
+ for (let i = 0; i < argv.length; i++) {
53
+ const a = argv[i];
54
+ if (a === "-h")
55
+ flags.help = true;
56
+ else if (a === "-v")
57
+ flags.version = true;
58
+ else if (a.startsWith("--")) {
59
+ const eq = a.indexOf("=");
60
+ const k = eq > 0 ? a.slice(2, eq) : a.slice(2);
61
+ if (eq > 0)
62
+ flags[k] = a.slice(eq + 1);
63
+ else if (coGiaTri.has(k)) {
64
+ if (i + 1 >= argv.length)
65
+ throw new Error(`--${k} needs a value`);
66
+ flags[k] = argv[++i];
67
+ }
68
+ else
69
+ flags[k] = true;
70
+ }
71
+ else
72
+ positional.push(a);
73
+ }
74
+ const lenh = positional.shift() ?? "";
75
+ return { command: ALIAS[lenh.toLowerCase()] ?? lenh, positional, flags };
76
+ }
77
+ const GIOI = /^(male|female|m|f|nam|nữ|nu)$/i;
78
+ /** Run one command; returns the text to print (no trailing newline). */
79
+ export function run(argv, env) {
80
+ const { command, positional: p, flags } = parseArgs(argv);
81
+ if (flags.version)
82
+ return VERSION;
83
+ if (flags.help || command === "" || command === "help")
84
+ return HELP;
85
+ const lang = (typeof flags.lang === "string" ? flags.lang : "en");
86
+ const json = flags.json === true;
87
+ const opts = { color: env.color && flags.color !== false && flags["no-color"] !== true, width: env.width };
88
+ const country = typeof flags.country === "string" ? flags.country : undefined;
89
+ const can = (n, mau) => {
90
+ if (p.length < n)
91
+ throw new Error(`usage: nhatnguyet ${mau}`);
92
+ };
93
+ const dumpJson = (x) => JSON.stringify(x, (k, v) => (k === "raw" ? undefined : v), 2);
94
+ const theme = flags.theme === "dark" ? "dark" : "light";
95
+ const ghiSvg = (ve) => {
96
+ if (typeof flags.svg !== "string")
97
+ return;
98
+ (env.writeFile ?? writeFileSync)(flags.svg, ve() + "\n");
99
+ };
100
+ switch (command) {
101
+ case "ziwei": {
102
+ can(3, "ziwei <YYYY-MM-DD> <HH:MM> <male|female>");
103
+ 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 });
105
+ const extra = { decades: decadeLuck(chart), year: yearlyLuck(chart), patterns: findPatterns(chart) };
106
+ ghiSvg(() => ziWeiSvg(chart, { theme }));
107
+ if (json)
108
+ return dumpJson({ chart, ...extra });
109
+ return renderZiWei(chart, extra, opts);
110
+ }
111
+ case "bazi": {
112
+ can(2, "bazi <YYYY-MM-DD> [HH:MM] <male|female>");
113
+ const coGio = p.length >= 3 || !GIOI.test(p[1]);
114
+ if (coGio)
115
+ 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 });
117
+ ghiSvg(() => baZiSvg(chart, { theme, name: typeof flags.name === "string" ? flags.name : "" }));
118
+ return json ? dumpJson(chart) : renderBaZi(chart, opts);
119
+ }
120
+ case "lunar": {
121
+ can(1, "lunar <YYYY-MM-DD> [--country CN]");
122
+ const r = toLunar(p[0], { country, lang });
123
+ return json ? dumpJson(r) : renderLunar(r, opts);
124
+ }
125
+ case "solar": {
126
+ can(1, "solar <lunar YYYY-MM-DD> [--leap]");
127
+ const k = /^(-?\d+)-(\d+)-(\d+)$/.exec(p[0]);
128
+ if (!k)
129
+ throw new Error("lunar date must look like YYYY-MM-DD");
130
+ 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;
132
+ }
133
+ case "terms": {
134
+ can(1, "terms <year>");
135
+ const y = Number(p[0]);
136
+ const t = solarTerms(y, { country, lang });
137
+ return json ? dumpJson(t) : renderSolarTerms(y, t, lang, opts);
138
+ }
139
+ case "numerology": {
140
+ can(2, 'numerology "<full name>" <YYYY-MM-DD>');
141
+ const r = numerology({ name: p[0], birthDate: p[1], today: typeof flags.today === "string" ? flags.today : undefined, lang });
142
+ ghiSvg(() => numerologySvg(r, { theme }));
143
+ return json ? dumpJson(r) : renderNumerology(r, opts);
144
+ }
145
+ case "festivals": {
146
+ can(1, "festivals <year>");
147
+ const y = Number(p[0]);
148
+ const list = festivals(y, { lang });
149
+ return json ? dumpJson(list) : renderFestivals(y, list, lang, opts);
150
+ }
151
+ }
152
+ throw new Error(`unknown command "${command}". Try: nhatnguyet --help`);
153
+ }
154
+ function main() {
155
+ const out = process.stdout;
156
+ const env = process.env;
157
+ const ep = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
158
+ const color = env.NO_COLOR === undefined && (ep || (!!out.isTTY && env.TERM !== "dumb"));
159
+ const width = out.isTTY && out.columns ? Math.min(out.columns, 140) : 88;
160
+ try {
161
+ out.write(run(process.argv.slice(2), { color, width }) + "\n");
162
+ }
163
+ catch (e) {
164
+ process.stderr.write("nhatnguyet: " + (e instanceof Error ? e.message : String(e)) + "\n");
165
+ process.exitCode = 1;
166
+ }
167
+ }
168
+ // Chạy khi được gọi như chương trình (không chạy khi test nhập mô-đun).
169
+ const laChuongTrinh = (() => {
170
+ const a = process.argv[1] ?? "";
171
+ return /(?:^|[\\/])(?:cli\.(?:ts|js)|nhatnguyet)$/.test(a) || a.includes("/.bin/") || a.includes("@nhatnguyet/cli");
172
+ })();
173
+ if (laChuongTrinh)
174
+ main();
@@ -0,0 +1,45 @@
1
+ import type { LunarResult, SolarTerm } from "@nhatnguyet/am-lich";
2
+ import type { ZiWeiChart, DecadeLuck, YearlyLuck, ZiWeiPattern } from "@nhatnguyet/tu-vi";
3
+ import type { BaZiChart } from "@nhatnguyet/bat-tu";
4
+ import type { NumerologyResult } from "@nhatnguyet/than-so-hoc";
5
+ import type { Festival } from "@nhatnguyet/le-hoi";
6
+ type Lang = "vi" | "en" | "zh";
7
+ /** Rendering options. */
8
+ export interface RenderOptions {
9
+ /** Use ANSI colours. Default false. */
10
+ color?: boolean;
11
+ /** Total width available, in terminal columns. Default 88. */
12
+ width?: number;
13
+ }
14
+ /** Terminal columns taken by one code point: 2 for CJK and fullwidth, 0 for combining marks. */
15
+ export declare function charWidth(cp: number): number;
16
+ /** Display width of a string (no ANSI codes inside). */
17
+ export declare function displayWidth(s: string): number;
18
+ /** Cut a string to at most `width` columns, ending with "…" when cut. */
19
+ export declare function truncate(s: string, width: number): string;
20
+ /** Wrap words into lines of at most `width` columns (CJK text breaks anywhere). */
21
+ export declare function wrap(s: string, width: number): string[];
22
+ /** Pack items into lines of at most `width` columns, never splitting an item (long items are cut). */
23
+ export declare function wrapItems(items: string[], sep: string, width: number): string[];
24
+ /**
25
+ * The Zi Wei chart as a 4x4 grid: the twelve palaces around the edge (Tỵ at
26
+ * the top left, as in printed charts), birth data in the middle.
27
+ */
28
+ export declare function renderZiWeiGrid(chart: ZiWeiChart, opts?: RenderOptions): string;
29
+ /** Grid plus the viewing year, ten-year periods, patterns and notes. */
30
+ export declare function renderZiWei(chart: ZiWeiChart, extra: {
31
+ decades?: DecadeLuck[];
32
+ year?: YearlyLuck;
33
+ patterns?: ZiWeiPattern[];
34
+ }, opts?: RenderOptions): string;
35
+ /** The four pillars as a table, then the luck pillars. */
36
+ export declare function renderBaZi(chart: BaZiChart, opts?: RenderOptions): string;
37
+ /** A lunar date as a small key-value box. */
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;
41
+ /** Numerology numbers, the 3x3 birth-date grid, pinnacles and challenges. */
42
+ export declare function renderNumerology(r: NumerologyResult, opts?: RenderOptions): string;
43
+ /** Festivals of a year as a table: date, fixed date, name. */
44
+ export declare function renderFestivals(year: number, list: Festival[], lang: Lang, opts?: RenderOptions): string;
45
+ export {};