node-lifecycle 1.0.2

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) 2025 Kelsey Salguera
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 ADDED
@@ -0,0 +1,96 @@
1
+ # node-lifecycle
2
+
3
+ Check the lifecycle status (Current, Active LTS, Maintenance, or EOL) of any Node.js version โ€” right from your terminal.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/node-lifecycle.svg)](https://www.npmjs.com/package/node-lifecycle)
6
+ [![license](https://img.shields.io/npm/l/node-lifecycle.svg)](LICENSE)
7
+
8
+
9
+ ---
10
+
11
+ ## ๐Ÿ“ฆ Installation
12
+
13
+ Install globally to use the CLI anywhere:
14
+
15
+ ```bash
16
+ npm install -g node-lifecycle
17
+ ```
18
+
19
+ Or run without installing globally:
20
+
21
+ ```
22
+ npx node-lifecycle
23
+ ```
24
+
25
+ ## ๐Ÿš€ Usage
26
+
27
+ Check the status of your current Node.js version:
28
+
29
+ ```
30
+ node-lifecycle
31
+ ```
32
+
33
+ Check the status of a specific version:
34
+
35
+ ```
36
+ node-lifecycle --version=18.20.4
37
+ ```
38
+
39
+ ## โš™๏ธ Options
40
+
41
+ | Flag | Description |
42
+ | ------------------ | --------------------------------------------------------------------------------- |
43
+ | `--version=VER` | Check this specific Node.js version instead of your current runtime. |
44
+ | `--warn-days=N` | Warn if EOL is within `N` days (default: `180`). |
45
+ | `--cache-ttl=SECS` | Cache the Node.js release schedule for `N` seconds (default: `86400` / 24 hours). |
46
+ | `--no-fail` | Do not exit with code `2` on EOL (still prints โŒ). |
47
+ | `--help` | Show help message. |
48
+
49
+ ## ๐Ÿ“‹ Examples
50
+
51
+ Check a Node version close to EOL:
52
+
53
+ ```
54
+ node-lifecycle --version=20.5.0
55
+ ```
56
+
57
+ Use a shorter warning window:
58
+
59
+ ```
60
+ node-lifecycle --warn-days=30
61
+ ```
62
+
63
+ Check with no failure on EOL (useful for CI logs):
64
+
65
+ ```
66
+ node-lifecycle --version=18.20.4 --no-fail
67
+ ```
68
+
69
+ ## Exit Codes
70
+
71
+ | Code | Meaning |
72
+ | ---- | ------------------------------------------ |
73
+ | `0` | OK (supported) |
74
+ | `1` | Warning (within `warn-days` of EOL) |
75
+ | `2` | EOL (unless `--no-fail` is used, then `0`) |
76
+
77
+
78
+ ## ๐Ÿงช CI Integration
79
+
80
+ Example GitHub Actions job to fail if Node.js is near or past EOL:
81
+
82
+ ```
83
+ jobs:
84
+ check-node-lifecycle:
85
+ runs-on: ubuntu-latest
86
+ steps:
87
+ - uses: actions/checkout@v4
88
+ - run: npm install -g node-lifecycle
89
+ - run: node-lifecycle
90
+ ```
91
+
92
+ ## ๐Ÿ“„ License
93
+
94
+ MIT ยฉ 2025 Kelsey Salguera
95
+
96
+ Note: This tool fetches Node.js release schedules from official sources (nodejs/Release and endoflife.date) and caches them locally for faster performance.
package/dist/cli.js ADDED
@@ -0,0 +1,104 @@
1
+ #!/usr/bin/env node
2
+ import { getSchedule, classify } from "./index.js";
3
+ import { findActiveLTS, findCurrent, formatFriendlyDate, codenameFor, } from "./utils.js";
4
+ /* ---------------- Arg Passing ---------------- */
5
+ function getArg(name) {
6
+ const pfx = `--${name}=`;
7
+ const hit = process.argv.find((a) => a.startsWith(pfx));
8
+ return hit ? hit.slice(pfx.length) : undefined;
9
+ }
10
+ const hasFlag = (name) => process.argv.includes(`--${name}`);
11
+ function printHelp() {
12
+ console.log(`Usage: node-lifecycle [--warn-days=N] [--version=X.Y.Z] [--cache-ttl=SECS] [--no-fail]
13
+
14
+ Checks the Node.js version lifecycle (current/LTS/maintenance/EOL).
15
+
16
+ Flags:
17
+ --warn-days=N Warn (exit 1) if EOL is within N days (default: 180).
18
+ --version=VER Check this specific version (default: process.version).
19
+ --cache-ttl=SECS Schedule cache TTL in seconds (default: 86400 via env or built-in).
20
+ --no-fail Do not fail (exit 2) on EOL; print โŒ but exit 0.
21
+ --help Show this help message.
22
+
23
+ Exit codes:
24
+ 0 = OK (supported)
25
+ 1 = Warning (within warn-days of EOL)
26
+ 2 = EOL (unless --no-fail, then 0)
27
+ `);
28
+ }
29
+ /* ---------------- Flags ---------------- */
30
+ if (hasFlag("help")) {
31
+ printHelp();
32
+ process.exit(0);
33
+ }
34
+ const argVersion = getArg("version");
35
+ // --warn-days (default 180)
36
+ const warnDaysRaw = getArg("warn-days");
37
+ const warnDays = warnDaysRaw === undefined ? 180 : Number(warnDaysRaw);
38
+ if (!Number.isFinite(warnDays) || warnDays < 0) {
39
+ console.error(`Invalid --warn-days value: ${warnDaysRaw}`);
40
+ process.exit(2);
41
+ }
42
+ const noFail = hasFlag("no-fail");
43
+ // --cache-ttl in seconds โ†’ ms
44
+ const cacheTtlRaw = getArg("cache-ttl");
45
+ const cacheTtlMs = cacheTtlRaw === undefined
46
+ ? undefined
47
+ : (Number(cacheTtlRaw) >= 0 ? Number(cacheTtlRaw) * 1000 : undefined);
48
+ if (cacheTtlRaw !== undefined && cacheTtlMs === undefined) {
49
+ console.error(`Invalid --cache-ttl value: ${cacheTtlRaw}`);
50
+ process.exit(2);
51
+ }
52
+ async function main() {
53
+ const schedule = await getSchedule({ cacheTtlMs });
54
+ const runtime = argVersion ?? process.version;
55
+ const result = classify(runtime, schedule);
56
+ // helper to build recommendation list
57
+ const buildRecommendations = () => {
58
+ const rec = [];
59
+ const ltsList = findActiveLTS(schedule); // e.g., [22, 20]
60
+ const topLts = ltsList[0]; // highest active LTS
61
+ const current = findCurrent(schedule); // e.g., 24
62
+ // Only recommend LTS if it's newer than the user's major
63
+ if (Number.isFinite(topLts) && topLts > result.major) {
64
+ const name = codenameFor(topLts);
65
+ rec.push(`LTS v${topLts}${name ? ` (โ€œ${name}โ€)` : ""}`);
66
+ }
67
+ // Always recommend Current unless they're already on it
68
+ if (current && current !== result.major) {
69
+ const name = codenameFor(current);
70
+ rec.push(`Current v${current}${name ? ` (โ€œ${name}โ€)` : ""}`);
71
+ }
72
+ return rec;
73
+ };
74
+ // EOL โ†’ fail (unless --no-fail)
75
+ if (result.status === "eol") {
76
+ const eolPretty = formatFriendlyDate(result.eol);
77
+ console.error(`โŒ Node ${runtime} (major ${result.major}) is EOL as of ${result.eol} (${eolPretty}).`);
78
+ const rec = buildRecommendations();
79
+ if (rec.length)
80
+ console.error(`Recommendation: Update to ${rec.join(" or ")}.`);
81
+ process.exit(noFail ? 0 : 2);
82
+ }
83
+ // Unknown line โ†’ warn (non-fatal)
84
+ if (result.status === "unknown") {
85
+ console.warn(`โš ๏ธ Node ${runtime} โ†’ unknown release line (no schedule data).`);
86
+ process.exit(1);
87
+ }
88
+ // Near-EOL window
89
+ if (typeof result.daysToEol === "number" && result.daysToEol <= warnDays) {
90
+ const eolPretty = formatFriendlyDate(result.eol);
91
+ console.warn(`โš ๏ธ Node ${runtime} (major ${result.major}) โ†’ ${result.status}. EOL ${result.eol} (${eolPretty}) in ${result.daysToEol} days.`);
92
+ const rec = buildRecommendations();
93
+ if (rec.length)
94
+ console.warn(`Consider upgrading to ${rec.join(" or ")}.`);
95
+ process.exit(1);
96
+ }
97
+ // Supported OK
98
+ const eolPretty = formatFriendlyDate(result.eol);
99
+ const code = codenameFor(result.major);
100
+ const suffix = code ? ` (โ€œ${code}โ€)` : "";
101
+ console.log(`โœ… Node ${runtime} (major ${result.major})${suffix} โ†’ ${result.status}. EOL ${result.eol} (${eolPretty}) in ${result.daysToEol} days.`);
102
+ process.exit(0);
103
+ }
104
+ main();
package/dist/index.js ADDED
@@ -0,0 +1,140 @@
1
+ import semver from "semver";
2
+ import fs from "node:fs/promises";
3
+ import os from "node:os";
4
+ import path from "node:path";
5
+ /* ---------------- cache helpers ---------------- */
6
+ const DEFAULT_TTL_MS = Number(process.env.NODE_EOL_CACHE_TTL ?? 24 * 60 * 60 * 1000); // 24h
7
+ function cacheDir() {
8
+ const home = os.homedir();
9
+ const xdg = process.env.XDG_CACHE_HOME || (home ? path.join(home, ".cache") : "");
10
+ return process.env.NODE_EOL_CACHE_DIR || (xdg ? path.join(xdg, "node-lifecycle") : path.join(os.tmpdir(), "node-lifecycle"));
11
+ }
12
+ function cachePath(name) {
13
+ return path.join(cacheDir(), name);
14
+ }
15
+ async function readCache(name, ttlMs) {
16
+ try {
17
+ const p = cachePath(name);
18
+ const stat = await fs.stat(p);
19
+ const age = Date.now() - stat.mtimeMs;
20
+ if (age > ttlMs)
21
+ return null;
22
+ const raw = await fs.readFile(p, "utf8");
23
+ return JSON.parse(raw);
24
+ }
25
+ catch {
26
+ return null;
27
+ }
28
+ }
29
+ async function writeCache(name, data) {
30
+ try {
31
+ await fs.mkdir(cacheDir(), { recursive: true });
32
+ await fs.writeFile(cachePath(name), JSON.stringify(data), "utf8");
33
+ }
34
+ catch {
35
+ /* ignore cache write errors */
36
+ }
37
+ }
38
+ /* ---------------- fetchers ---------------- */
39
+ async function fetchJson(url) {
40
+ const r = await fetch(url, { cache: "no-store" });
41
+ if (!r.ok)
42
+ throw new Error(`${url} -> ${r.status}`);
43
+ return r.json();
44
+ }
45
+ async function fetchWG(ttlMs) {
46
+ const url = "https://raw.githubusercontent.com/nodejs/Release/HEAD/schedule.json";
47
+ const cacheName = "schedule.wg.json";
48
+ const cached = await readCache(cacheName, ttlMs);
49
+ if (cached)
50
+ return cached;
51
+ const data = (await fetchJson(url));
52
+ await writeCache(cacheName, data);
53
+ return data;
54
+ }
55
+ function normalizeEndOfLife(arr) {
56
+ const out = {};
57
+ for (const line of arr) {
58
+ const majorNum = Number(line.cycle);
59
+ const eol = line.eol ?? undefined;
60
+ if (!Number.isFinite(majorNum) || !eol)
61
+ continue;
62
+ out[String(majorNum)] = { end: eol };
63
+ }
64
+ return out;
65
+ }
66
+ async function fetchEoL(ttlMs) {
67
+ const url = "https://endoflife.date/api/nodejs.json";
68
+ const cacheName = "schedule.eol.json";
69
+ const cached = await readCache(cacheName, ttlMs);
70
+ if (cached)
71
+ return cached;
72
+ const payload = (await fetchJson(url));
73
+ const normalized = normalizeEndOfLife(payload);
74
+ await writeCache(cacheName, normalized);
75
+ return normalized;
76
+ }
77
+ /* ---------------- API ---------------- */
78
+ export async function getSchedule(opts) {
79
+ const ttlMs = opts?.cacheTtlMs ?? DEFAULT_TTL_MS;
80
+ try {
81
+ const wg = await fetchWG(ttlMs);
82
+ try {
83
+ const eol = await fetchEoL(ttlMs);
84
+ return { ...eol, ...wg }; // WG overrides EoL
85
+ }
86
+ catch {
87
+ return wg;
88
+ }
89
+ }
90
+ catch {
91
+ try {
92
+ return await fetchEoL(ttlMs);
93
+ }
94
+ catch {
95
+ return {};
96
+ }
97
+ }
98
+ }
99
+ // Date-only (UTC) diff in days; returns +Infinity if target is invalid/missing
100
+ function daysUntil(iso, now = new Date()) {
101
+ if (!iso)
102
+ return Number.POSITIVE_INFINITY;
103
+ const d = new Date(iso);
104
+ if (Number.isNaN(d.getTime()))
105
+ return Number.POSITIVE_INFINITY;
106
+ const todayUtc = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
107
+ const targetUtc = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
108
+ return Math.ceil((targetUtc - todayUtc) / 86400000);
109
+ }
110
+ export function classify(nodeVersion, schedule) {
111
+ const coerced = semver.coerce(nodeVersion);
112
+ if (!coerced)
113
+ return { major: NaN, status: "unknown" };
114
+ const major = semver.major(coerced);
115
+ const rel = schedule[String(major)];
116
+ // Missing release line entirely
117
+ if (!rel)
118
+ return { major, status: "unknown" };
119
+ const now = new Date();
120
+ // If no end date or invalid date โ†’ unknown
121
+ if (!rel.end || Number.isNaN(new Date(rel.end).getTime())) {
122
+ return { major, status: "unknown" };
123
+ }
124
+ const eolDays = daysUntil(rel.end, now);
125
+ const isEol = eolDays <= 0;
126
+ let status;
127
+ if (isEol) {
128
+ status = "eol";
129
+ }
130
+ else if (rel.maintenance && new Date(rel.maintenance) <= now) {
131
+ status = "maintenance";
132
+ }
133
+ else if (rel.lts && new Date(rel.lts) <= now) {
134
+ status = "active-lts";
135
+ }
136
+ else {
137
+ status = "current";
138
+ }
139
+ return { major, status, eol: rel.end, daysToEol: Number.isFinite(eolDays) ? eolDays : undefined };
140
+ }
package/dist/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/dist/utils.js ADDED
@@ -0,0 +1,98 @@
1
+ export const CODENAMES = {
2
+ 18: "Hydrogen",
3
+ 20: "Iron",
4
+ 22: "Jod",
5
+ 24: "Krypton",
6
+ };
7
+ const toValidDate = (iso) => {
8
+ if (!iso)
9
+ return null;
10
+ const d = new Date(iso);
11
+ return Number.isNaN(d.getTime()) ? null : d;
12
+ };
13
+ // ISO โ†’ friendly date without TZ drift
14
+ export function formatFriendlyDate(isoDate) {
15
+ if (!isoDate)
16
+ return "";
17
+ const parts = isoDate.split("-");
18
+ if (parts.length !== 3)
19
+ return isoDate;
20
+ const [y, m, d] = parts.map(Number);
21
+ if (!y || !m || !d)
22
+ return isoDate;
23
+ const utc = new Date(Date.UTC(y, m - 1, d));
24
+ return utc.toLocaleDateString(undefined, {
25
+ year: "numeric", month: "long", day: "numeric", timeZone: "UTC",
26
+ });
27
+ }
28
+ /**
29
+ * Return ALL active LTS majors.
30
+ * Normal path: require ltsStart <= now && eol > now.
31
+ * Fallback path (when no majors have an `lts` field at all, e.g. endoflife.date only):
32
+ * infer LTS = even majors with eol > now, EXCLUDING the highest supported major (assumed Current).
33
+ */
34
+ export function findActiveLTS(schedule, now = new Date()) {
35
+ const keys = Object.keys(schedule);
36
+ if (keys.length === 0)
37
+ return [];
38
+ const majors = keys.map(Number).filter(Number.isFinite);
39
+ const anyLtsInfo = majors.some((m) => !!schedule[String(m)]?.lts);
40
+ if (anyLtsInfo) {
41
+ return majors
42
+ .filter((m) => {
43
+ const r = schedule[String(m)];
44
+ if (!r)
45
+ return false;
46
+ const eol = toValidDate(r.end);
47
+ const ltsStart = toValidDate(r.lts);
48
+ return !!ltsStart && ltsStart <= now && !!eol && eol > now;
49
+ })
50
+ .sort((a, b) => b - a);
51
+ }
52
+ // Fallback inference
53
+ const supported = majors.filter((m) => {
54
+ const e = toValidDate(schedule[String(m)]?.end);
55
+ return !!e && e > now;
56
+ });
57
+ if (!supported.length)
58
+ return [];
59
+ const highestSupported = Math.max(...supported); // assumed Current
60
+ return supported
61
+ .filter((m) => m !== highestSupported && m % 2 === 0)
62
+ .sort((a, b) => b - a);
63
+ }
64
+ /**
65
+ * Latest Current (supported & not yet LTS).
66
+ * Fallback (no `lts` fields): the highest supported major.
67
+ */
68
+ export function findCurrent(schedule, now = new Date()) {
69
+ const keys = Object.keys(schedule);
70
+ if (keys.length === 0)
71
+ return null;
72
+ const majors = keys.map(Number).filter(Number.isFinite);
73
+ const anyLtsInfo = majors.some((m) => !!schedule[String(m)]?.lts);
74
+ if (anyLtsInfo) {
75
+ const candidates = majors.filter((m) => {
76
+ const r = schedule[String(m)];
77
+ if (!r)
78
+ return false;
79
+ const eol = toValidDate(r.end);
80
+ const ltsStart = toValidDate(r.lts);
81
+ if (!eol || eol <= now)
82
+ return false;
83
+ return !ltsStart || ltsStart > now; // not yet LTS
84
+ });
85
+ return candidates.length ? Math.max(...candidates) : null;
86
+ }
87
+ // Fallback: highest supported major
88
+ const supported = majors.filter((m) => {
89
+ const e = toValidDate(schedule[String(m)]?.end);
90
+ return !!e && e > now;
91
+ });
92
+ return supported.length ? Math.max(...supported) : null;
93
+ }
94
+ export function codenameFor(major) {
95
+ if (!Number.isFinite(major))
96
+ return "";
97
+ return CODENAMES[major] || "";
98
+ }
package/package.json ADDED
@@ -0,0 +1,53 @@
1
+ {
2
+ "name": "node-lifecycle",
3
+ "version": "1.0.2",
4
+ "description": "CLI tool to check Node.js version lifecycle and EOL status",
5
+ "type": "module",
6
+ "bin": {
7
+ "node-lifecycle": "./dist/cli.js"
8
+ },
9
+ "files": [
10
+ "dist"
11
+ ],
12
+ "scripts": {
13
+ "build": "tsc",
14
+ "start": "ts-node src/cli.ts",
15
+ "test": "jest",
16
+ "test:watch": "jest --watch",
17
+ "prepublishOnly": "npm run build"
18
+ },
19
+ "keywords": [
20
+ "node",
21
+ "cli",
22
+ "lifecycle",
23
+ "eol",
24
+ "nodejs",
25
+ "lts",
26
+ "maintenance"
27
+ ],
28
+ "author": "Kelsey Salguera",
29
+ "license": "MIT",
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git@github.com:ksalguera/node-lifecycle.git"
33
+ },
34
+ "bugs": {
35
+ "url": "https://github.com/ksalguera/node-lifecycle/issues"
36
+ },
37
+ "homepage": "https://github.com/ksalguera/node-lifecycle#readme",
38
+ "dependencies": {
39
+ "semver": "^7.6.0"
40
+ },
41
+ "devDependencies": {
42
+ "@types/jest": "^30.0.0",
43
+ "@types/node": "^20.0.0",
44
+ "@types/semver": "^7.5.8",
45
+ "jest": "^29.7.0",
46
+ "ts-jest": "^29.4.1",
47
+ "ts-node": "^10.9.1",
48
+ "typescript": "^5.0.0"
49
+ },
50
+ "engines": {
51
+ "node": ">=18.0.0"
52
+ }
53
+ }