create-packkit 2.0.1 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "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": {

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 { nodeFloor, 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 = nodeFloor(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/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 { nodeFloor } from '../node.js';
 
 export default {
   id: 'meta',
@@ -119,6 +115,13 @@ function readme(cfg) {
   const badges = makeBadges(cfg);
   if (badges) lines.push(badges, '');
 
+  lines.push(
+    '## Requirements',
+    '',
+    `Node.js >= ${nodeFloor(cfg.nodeVersion)} (\`.nvmrc\` pins it; 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.js

@@ -0,0 +1,22 @@
+// Shared Node-version floor logic. Browser-safe (no node builtins) so both the
+// generator and the CLI preflight agree on exactly one source of truth.
+
+// The real minimum patch for each supported major, driven by our template deps
+// (eslint 10, jsdom 29, vite 8 need ^20.19; vite/others need ^22.12). Writing a
+// bare ">=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' };
+
+export const nodeFloor = (v) => NODE_FLOOR[v] || `${v}.0.0`;
+
+const parts = (s) =>
+  String(s).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+
+/** True if `current` (e.g. "v20.17.0" or process.version) is >= `floor` ("20.19.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;
+}