create-packkit 2.0.1 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Highly configurable scaffolder for modern npm packages and CLIs — pick your stack (TS/JS, bundler, tests, linter, CI, releases) from a CLI or a web configurator.",
   "type": "module",
   "bin": {
@@ -26,7 +26,8 @@
     "test": "node --test",
     "check:deps": "node scripts/check-template-deps.mjs",
     "integration": "node scripts/integration.mjs",
-    "build:web": "esbuild src/core/index.js --bundle --format=esm --outfile=docs/packkit-core.js"
+    "build:web": "esbuild src/core/index.js --bundle --format=esm --outfile=docs/packkit-core.js",
+    "update:node": "node scripts/update-node-versions.mjs"
   },
   "repository": {
     "type": "git",

package/src/cli/index.js

@@ -3,6 +3,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import { generate, fromPreset, normalizeConfig, PRESET_NAMES, OPTIONS, PRESET_INFO, PRESET_ALIASES } from '../core/index.js';
+import { engineFloor, meetsNodeFloor } from '../core/node.js';
 import { parseCliArgs } from './args.js';
 import { runWizard } from './wizard.js';
 import { writeProject, dirIsEmptyOrMissing, gitInit, installDeps } from './write.js';
@@ -87,6 +88,25 @@ export async function run(argv = process.argv.slice(2)) {
   config.gitInit = args.git;
   config.install = args.install;
 
+  // Node preflight: the generated project's tools (eslint, vite, vitest) hard-
+  // require this floor. npm only *warns* on engines, so catch it here — clearly,
+  // once — instead of letting a doomed install spew EBADENGINE and leave a broken
+  // project. This is the signal both humans and agents need up front.
+  const floor = engineFloor(config.nodeVersion);
+  const nodeOk = meetsNodeFloor(process.version, floor);
+  if (!nodeOk) {
+    const lines = [
+      `Node ${process.version} is below this project's required Node >= ${floor}.`,
+      `Tools like eslint, vite and vitest will not run on it.`,
+      `Fix: nvm install ${config.nodeVersion}   (or install any Node >= ${floor})`,
+    ];
+    if (config.install) {
+      lines.push(`Skipping the dependency install until Node is upgraded.`);
+      config.install = false;
+    }
+    if (interactive) p.log.warn(lines.join('\n')); else console.error('\n⚠  ' + lines.join('\n   '));
+  }
+
   // Resolve the target directory.
   const targetDir = args.here ? process.cwd() : resolve(process.cwd(), config.name);
   if (!args.here && !config.name) {
@@ -119,13 +139,25 @@ export async function run(argv = process.argv.slice(2)) {
     config.test !== 'none' ? `${runWord(config)} test` : null,
   ].filter(Boolean);
 
+  // Clarify things that surprise people: a framework *library* has no dev
+  // server (its `dev` just rebuilds), and the Node floor this project needs.
+  const componentLib = config.hasFramework && config.hasLibrary && !config.hasApp;
+  const hints = [
+    componentLib
+      ? `This is a ${config.framework} component library — \`${runWord(config)} dev\` rebuilds on change (there's no dev server). For a runnable app, scaffold the "${config.framework}-app" preset instead.`
+      : null,
+    `Requires Node >= ${floor}${nodeOk ? '' : ` — you're on ${process.version}, upgrade first`}.`,
+  ].filter(Boolean);
+
   const done = `Created ${summary.name} — ${summary.fileCount} files · ${summary.stack.join(' · ')}`;
   if (interactive) {
     p.note(next.join('\n') || 'You are all set.', 'Next steps');
+    if (hints.length) p.log.info(hints.join('\n'));
     p.outro(done);
   } else {
     console.log(done);
     if (next.length) console.log('\nNext steps:\n  ' + next.join('\n  '));
+    if (hints.length) console.log('\n' + hints.map((h) => '• ' + h).join('\n'));
   }
 
   const latest = await checkForUpdate(pkgVersion());

package/src/core/features/gitfiles.js

@@ -39,11 +39,17 @@ indent_style = space
 indent_size = 2
 `;
 
+// engine-strict turns npm/pnpm's `engines` warning into a hard install error, so
+// a contributor, CI job, or agent on an unsupported Node fails immediately with a
+// clear message instead of a broken install they scroll past.
+const NPMRC = `engine-strict=true
+`;
+
 export default {
   id: 'gitfiles',
   active: () => true,
   apply(cfg) {
-    const files = { '.gitignore': GITIGNORE };
+    const files = { '.gitignore': GITIGNORE, '.npmrc': NPMRC };
     if (cfg.editorconfig) files['.editorconfig'] = EDITORCONFIG;
     return { files, pkg: {} };
   },

package/src/core/features/githooks.js

@@ -34,8 +34,8 @@ export default {
 
     if (needsLintStaged) {
       pkg['lint-staged'] = staged;
-      // Held at 16: v17 requires Node >=22.22.1, which would silently drop
-      // Node 20 LTS support for every generated project. See NODE_FLOOR.
+      // Held at 16: v17 requires Node >=22.22.1, above our Node 22 engines
+      // floor (22.13) — it would break the Maintenance-LTS line. See ENGINE_MIN.
       pkg.devDependencies['lint-staged'] = '^16.2.0';
     }
 

package/src/core/features/meta.js

@@ -1,10 +1,6 @@
 // Always-on: base package.json descriptive fields + the source entry + README.
 
-// The real minimum patch for each major, driven by our template deps (eslint 10,
-// jsdom 29, vite 8 need ^20.19; vite/others need ^22.12). `>=20` would be a lie —
-// a user on 20.17 hits EBADENGINE and transitive syntax errors. Keep this honest.
-export const NODE_FLOOR = { 18: '18.18.0', 20: '20.19.0', 22: '22.12.0', 24: '24.0.0' };
-const nodeFloor = (v) => NODE_FLOOR[v] || `${v}.0.0`;
+import { engineFloor, nodePin } from '../node.js';
 
 export default {
   id: 'meta',
@@ -16,7 +12,7 @@ export default {
       version: '0.0.0',
       description: cfg.description || '',
       type: cfg.moduleFormat === 'cjs' ? 'commonjs' : 'module',
-      engines: { node: `>=${nodeFloor(cfg.nodeVersion)}` },
+      engines: { node: `>=${engineFloor(cfg.nodeVersion)}` },
       scripts: {},
     };
 
@@ -39,8 +35,9 @@ export default {
     // README
     files['README.md'] = readme(cfg);
 
-    // Node version pin — the honest floor, so `nvm use` can't land below it.
-    files['.nvmrc'] = `${nodeFloor(cfg.nodeVersion)}\n`;
+    // Node version pin — that line's newest patch (from Node's own data), so
+    // `nvm use` lands on a current, real release.
+    files['.nvmrc'] = `${nodePin(cfg.nodeVersion)}\n`;
 
     // A typecheck script for TS projects — framework-aware (plain tsc can't
     // resolve .vue/.svelte modules).
@@ -119,6 +116,13 @@ function readme(cfg) {
   const badges = makeBadges(cfg);
   if (badges) lines.push(badges, '');
 
+  lines.push(
+    '## Requirements',
+    '',
+    `Node.js >= ${engineFloor(cfg.nodeVersion)} (\`.nvmrc\` pins ${nodePin(cfg.nodeVersion)}; run \`nvm use\`). Enforced via \`engine-strict\`, so installs fail fast on an unsupported version.`,
+    '',
+  );
+
   lines.push('## Install', '', '```sh', install, '```', '');
 
   if (cfg.hasApp) {

package/src/core/node-versions.js

@@ -0,0 +1,12 @@
+// AUTO-GENERATED by scripts/update-node-versions.mjs — do not edit by hand.
+// Source: nodejs.org/dist + nodejs/Release schedule, refreshed 2026-07-14.
+// Offered lines track the Node release schedule; each version is that line's
+// newest published patch. Run `node scripts/update-node-versions.mjs` to refresh.
+
+export const NODE_LINES = {
+  '24': { version: '24.18.0', status: 'active-lts', codename: 'Krypton', label: '24 (Active LTS, "Krypton")' },
+  '22': { version: '22.23.1', status: 'maintenance', codename: 'Jod', label: '22 (Maintenance LTS, "Jod")' },
+  '26': { version: '26.5.0', status: 'current', codename: null, label: '26 (Current)' },
+};
+
+export const DEFAULT_NODE = '24';

package/src/core/node.js

@@ -0,0 +1,34 @@
+// Shared Node-version logic. Browser-safe (no node builtins) so the generator
+// and the CLI preflight agree on exactly one source of truth.
+//
+// Two concerns, two sources:
+//   - which majors we offer + the exact patch to pin  -> node-versions.js,
+//     auto-derived from Node's release schedule + dist index (never guessed).
+//   - the minimum patch *within a major* our template deps need -> ENGINE_MIN,
+//     below, driven by our deps (eslint/vite), governed by the template-deps
+//     freshness workflow. These change rarely and independently of Node.
+
+import { NODE_LINES, DEFAULT_NODE } from './node-versions.js';
+
+export { NODE_LINES, DEFAULT_NODE };
+
+// eslint 10 needs ^20.19/^22.13; vite 8 needs ^20.19/^22.12 — take the max.
+export const ENGINE_MIN = { 18: '18.18.0', 20: '20.19.0', 22: '22.13.0' };
+
+/** The `engines` minimum for a target major (a floor, not a pin). */
+export const engineFloor = (v) => ENGINE_MIN[v] || `${v}.0.0`;
+
+/** The exact version to pin in `.nvmrc` — that line's newest patch, or the floor. */
+export const nodePin = (v) => NODE_LINES[v]?.version || engineFloor(v);
+
+const parts = (s) =>
+  String(s).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+
+/** True if `current` (e.g. "v22.5.0" or process.version) is >= `floor` ("22.13.0"). */
+export function meetsNodeFloor(current, floor) {
+  const [a, b, c] = parts(current);
+  const [x, y, z] = parts(floor);
+  if (a !== x) return a > x;
+  if (b !== y) return b > y;
+  return c >= z;
+}

package/src/core/options.js

@@ -2,8 +2,14 @@
 // Both the CLI wizard and the web configurator render from this schema, and
 // `normalizeConfig` turns partial/user input into a complete, valid config.
 
+import { NODE_LINES, DEFAULT_NODE } from './node.js';
+
 /** @typedef {'select'|'multiselect'|'boolean'|'text'} OptionType */
 
+// Node choices are derived from Node's own release schedule (see node-versions.js)
+// so the LTS/Current lines and their patches stay current without hand-editing.
+const NODE_CHOICES = Object.entries(NODE_LINES).map(([value, info]) => ({ value, label: info.label }));
+
 export const OPTIONS = {
   // ---- package metadata ----
   name: { group: 'meta', type: 'text', label: 'Package name', default: 'my-package' },
@@ -59,12 +65,8 @@ export const OPTIONS = {
     ],
   },
   nodeVersion: {
-    group: 'core', type: 'select', label: 'Node version', default: '20',
-    choices: [
-      { value: '20', label: '20 (LTS, ≥20.19)' },
-      { value: '22', label: '22 (LTS, ≥22.12)' },
-      { value: '24', label: '24 (Current)' },
-    ],
+    group: 'core', type: 'select', label: 'Node version', default: DEFAULT_NODE,
+    choices: NODE_CHOICES,
   },
 
   // ---- build ----