create-packkit 2.9.0 → 3.1.0

package/README.md

@@ -61,6 +61,22 @@ npx create-packkit ts-lib my-lib --here --merge
 
 **Existing files are never overwritten.** Anything that collides is left alone and reported, so you can diff at your leisure. (A directory containing only `.git` counts as empty — a fresh clone scaffolds without needing `--merge` at all.)
 
+## Keep a project current
+
+Every scaffolded project records what it came from in `packkit.json`. Later, from
+inside the project:
+
+```sh
+npx create-packkit upgrade          # dry run: what's changed since you scaffolded
+npx create-packkit upgrade --apply  # add new files, bump deps, keep your edits
+```
+
+Upgrade regenerates the project Packkit would produce today and reports the
+difference — new files, added or bumped dependencies, new scripts. `--apply`
+brings in the safe changes (your own files, deps, and scripts are preserved);
+files you've edited are listed for review and never overwritten unless you pass
+`--force`.
+
 ## Or configure it on the web
 
 No install needed: **[danmat.github.io/create-packkit](https://danmat.github.io/create-packkit/)** — tick the options, preview the file tree, and **download a zip** (or copy the equivalent `npx create-packkit` command). Everything runs in your browser.
@@ -193,14 +209,32 @@ There's also an [`llms.txt`](llms.txt) (served at [danmat.github.io/create-packk
 { "mcpServers": { "packkit": { "command": "npx", "args": ["-y", "packkit-mcp"] } } }
 ```
 
+## Embed Packkit in your own app
+
+Packkit ships a typed, side-effect-free API so a Node application can use it as a
+project-generation engine — generate in memory, add your own deployment files,
+and write to disk when you're ready. No prompts, installs, git, or network.
+
+```js
+import { createProject, extendProject, writeGeneratedProject } from 'create-packkit/embedded';
+
+const project = createProject({ preset: 'react-app', name: 'weather-dashboard' });
+const extended = extendProject(project, { files: { '.github/workflows/deploy.yml': deployYaml } });
+await writeGeneratedProject({ project: extended, destination: '/tmp/weather-dashboard' });
+```
+
+Full guide, including diagnostics, reproducible definitions, digests, and the
+provider-neutral deployment contract: **[Embedding Packkit](docs/EMBEDDING.md)**.
+
 ## How it works
 
 Packkit is a pure `config → { files }` **core** that runs in both Node and the browser:
 
 - the **CLI** writes the files to disk, runs `git init`, and installs dependencies;
-- the **web configurator** zips the same files client-side (no server).
+- the **web configurator** zips the same files client-side (no server);
+- the **embedded API** ([`create-packkit/embedded`](docs/EMBEDDING.md)) hands the file map to a host application.
 
-Both drive from one options schema ([`src/core/options.js`](src/core/options.js)), so the CLI and the web page always stay in sync.
+All three drive from one options schema ([`src/core/options.js`](src/core/options.js)), so they always stay in sync.
 
 ## Staying fresh
 

package/package.json

@@ -1,20 +1,34 @@
 {
   "name": "create-packkit",
-  "version": "2.9.0",
+  "version": "3.1.0",
   "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": {
     "create-packkit": "bin/cli.js"
   },
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/core/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
     "./core": "./src/core/index.js",
+    "./embedded": {
+      "types": "./types/embedded.d.ts",
+      "default": "./src/embedded/index.js"
+    },
+    "./writer": {
+      "types": "./types/writer.d.ts",
+      "default": "./src/embedded/writer.js"
+    },
     "./cli": "./src/cli/index.js",
-    "./scaffold": "./src/cli/write.js"
+    "./scaffold": "./src/cli/write.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "bin",
     "src",
+    "types",
     "README.md",
     "LICENSE",
     "llms.txt"
@@ -25,6 +39,8 @@
   "scripts": {
     "start": "node bin/cli.js",
     "test": "node --test",
+    "lint": "eslint .",
+    "check": "npm run lint && npm 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",
@@ -60,6 +76,9 @@
     "@clack/prompts": "^0.7.0"
   },
   "devDependencies": {
-    "esbuild": "^0.23.0"
+    "@eslint/js": "^10.0.1",
+    "esbuild": "^0.23.0",
+    "eslint": "^10.8.0",
+    "globals": "^17.8.0"
   }
 }

package/src/cli/args.js

@@ -53,7 +53,6 @@ export function parseCliArgs(argv) {
       minify: { type: 'boolean' },
       target: { type: 'string', multiple: true },
       workflows: { type: 'string', multiple: true },
-      minify: { type: 'boolean' },
       monorepo: { type: 'boolean' },
       storybook: { type: 'boolean' },
       e2e: { type: 'boolean' },

package/src/cli/index.js

@@ -2,12 +2,17 @@ import { resolve, basename } from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
-import { generate, fromPreset, normalizeConfig, PRESET_NAMES, OPTIONS, OPTION_HELP, PRESET_INFO, PRESET_ALIASES } from '../core/index.js';
+import { PRESET_NAMES, OPTIONS, OPTION_HELP, PRESET_INFO, PRESET_ALIASES } from '../core/index.js';
 import { engineFloor, meetsNodeFloor } from '../core/node.js';
+// The CLI is an adapter over the embedded API: it resolves + generates through
+// the same pipeline every other surface uses (so it shares diagnostics,
+// collision handling, and path safety), and adds the side effects the embedded
+// API deliberately never performs — git, install, and creating the remote.
+import { resolveProjectConfig, createProjectFromResolvedConfig, PackkitValidationError } from '../embedded/index.js';
+import { writeGeneratedProject } from '../embedded/writer.js';
 import { parseCliArgs } from './args.js';
 import { runWizard } from './wizard.js';
 import {
-  writeProject,
   existingEntries,
   gitInit,
   installDeps,
@@ -34,6 +39,7 @@ packkit — scaffold a modern npm package, CLI, service, or app
 Usage:
   npm create packkit@latest [name] [options]
   npx packkit [preset] [name] [options]
+  npx packkit upgrade [dir]                Pull a scaffolded project up to current templates
 
 Run with no options for an interactive wizard, or add -y for recommended
 defaults in one shot. Every option is documented (with why-you'd-use-it) at:
@@ -109,6 +115,13 @@ Examples:
 `;
 
 export async function run(argv = process.argv.slice(2)) {
+  // Subcommands take the first positional. `upgrade` is a distinct flow (it
+  // reads an existing project rather than scaffolding one), so route it early.
+  if (argv[0] === 'upgrade') {
+    const { runUpgrade } = await import('./upgrade.js');
+    return runUpgrade(argv.slice(1));
+  }
+
   const args = parseCliArgs(argv);
   if (args.help) return void console.log(HELP);
   if (args.version) return void console.log(pkgVersion());
@@ -125,21 +138,33 @@ export async function run(argv = process.argv.slice(2)) {
   const profile = loadProfile(args);
   const seed = { ...profile, ...args.overrides };
 
-  let config;
+  // Gather raw input for the embedded resolver — don't normalize here, so the
+  // resolver captures the coercions it makes (they surface as warnings below).
+  let rawInput;
+  let presetName;
   if (interactive) {
     p.intro('📦 Packkit');
-    config = normalizeConfig(await runWizard(seed));
+    rawInput = await runWizard(seed);
   } else if (args.preset) {
-    config = fromPreset(args.preset, seed);
+    presetName = args.preset;
+    rawInput = seed;
   } else {
-    config = normalizeConfig(seed);
+    rawInput = seed;
   }
+  // gitInit/install are real options, so they flow through resolution.
+  rawInput = { ...rawInput, gitInit: args.git, install: args.install };
 
-  config.gitInit = args.git;
-  config.install = args.install;
-  // Core is version-agnostic (it also runs in the browser), so the surface
-  // that knows the version supplies it for packkit.json.
-  config.generatorVersion = pkgVersion();
+  let config;
+  let diagnostics;
+  try {
+    ({ config, diagnostics } = resolveProjectConfig({ preset: presetName, config: rawInput }));
+  } catch (err) {
+    if (err instanceof PackkitValidationError) {
+      console.error(err.diagnostics.map((d) => `✖ ${d.message}`).join('\n'));
+      process.exit(1);
+    }
+    throw err;
+  }
 
   // Node preflight: the generated project's tools (eslint, vite, vitest) hard-
   // require this floor. npm only *warns* on engines, so catch it here — clearly,
@@ -186,9 +211,25 @@ export async function run(argv = process.argv.slice(2)) {
   }
   if (remote?.url && /^https?:/.test(remote.url)) config.repo = remote.url;
 
-  // Generate + write.
-  const { files, summary } = generate(config);
-  const { skipped } = await writeProject(targetDir, files, { merge: args.merge });
+  // Generate through the embedded pipeline (carrying the resolution diagnostics)
+  // and write through the safe writer. --merge maps to the 'skip' policy: write
+  // what's absent, keep what's there — never overwrite.
+  const project = createProjectFromResolvedConfig(config, { diagnostics });
+  const { summary } = project;
+
+  // Surface anything Packkit changed or flagged during resolution — a coercion
+  // (Storybook off for a service), an unknown option — before writing.
+  const warnings = project.diagnostics.filter((d) => d.severity === 'warning');
+  if (warnings.length) {
+    const lines = warnings.map((d) => d.message).join('\n');
+    if (interactive) p.log.warn(lines); else console.error('\n⚠  ' + warnings.map((d) => d.message).join('\n   '));
+  }
+
+  const { skippedFiles: skipped } = await writeGeneratedProject({
+    project,
+    destination: targetDir,
+    collisionPolicy: args.merge ? 'skip' : 'error',
+  });
 
   // Post steps.
   if (config.gitInit) gitInit(targetDir);

package/src/cli/upgrade.js

@@ -0,0 +1,147 @@
+// `packkit upgrade` — regenerate a scaffolded project's current recommended
+// output and report (or apply) what has drifted from Packkit's templates.
+//
+// It reads packkit.json to learn the preset + settings the project came from,
+// regenerates in memory through the embedded API, and diffs against disk. New
+// files and package.json dep/script updates apply cleanly; files that differ
+// are surfaced for review, never overwritten unless explicitly forced.
+
+import { parseArgs } from 'node:util';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { createProject, planUpgrade, isUpgradeEmpty, buildUpgradeWrite } from '../embedded/index.js';
+import { writeGeneratedProject } from '../embedded/writer.js';
+
+const UPGRADE_HELP = `
+packkit upgrade — pull your project up to Packkit's current templates
+
+Usage:
+  packkit upgrade [directory] [options]
+
+Reads packkit.json in the directory (default: current), regenerates the project
+Packkit would produce today, and shows what changed since you scaffolded.
+
+Options:
+  --apply        Write new files and update package.json / packkit.json
+  --force        With --apply, also overwrite files that differ (review first!)
+  -h, --help     Show this help
+
+Without --apply this is a dry run — it only reports.
+`;
+
+export async function runUpgrade(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      apply: { type: 'boolean' },
+      force: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+  if (values.help) return void console.log(UPGRADE_HELP);
+
+  const dir = resolve(positionals[0] || '.');
+  const provPath = join(dir, 'packkit.json');
+  if (!existsSync(provPath)) {
+    console.error(`No packkit.json in "${dir}". Upgrade only works on a project Packkit scaffolded.`);
+    process.exit(1);
+  }
+
+  let provenance;
+  try {
+    provenance = JSON.parse(readFileSync(provPath, 'utf8'));
+  } catch (err) {
+    console.error(`Could not read packkit.json: ${err.message}`);
+    process.exit(1);
+  }
+
+  // The project name isn't a "setting", so it lives in package.json, not
+  // packkit.json — read it back so regeneration reproduces the same names.
+  const name = readName(dir) || provenance.name || 'my-package';
+  const fromVersion = provenance.version || 'unknown';
+
+  let project;
+  try {
+    project = createProject({ preset: provenance.preset, name, config: provenance.settings || {} });
+  } catch (err) {
+    console.error(`Could not regenerate from packkit.json: ${err.message}`);
+    process.exit(1);
+  }
+  const toVersion = project.metadata.packkitVersion;
+
+  const onDisk = {};
+  for (const path of Object.keys(project.files)) {
+    const full = join(dir, path);
+    onDisk[path] = existsSync(full) ? readFileSync(full, 'utf8') : undefined;
+  }
+
+  const plan = planUpgrade({ generated: project.files, onDisk });
+
+  if (isUpgradeEmpty(plan)) {
+    console.log(`Already current with Packkit ${toVersion}. Nothing to upgrade.`);
+    return;
+  }
+
+  report(plan, fromVersion, toVersion);
+
+  if (!values.apply) {
+    console.log('\nThis was a dry run. Re-run with --apply to bring in the safe changes.');
+    return;
+  }
+
+  const writeMap = buildUpgradeWrite({ generated: project.files, onDisk, plan, includeChanged: !!values.force });
+  const paths = Object.keys(writeMap);
+  if (paths.length) {
+    await writeGeneratedProject({
+      project: { config: project.config, files: writeMap },
+      destination: dir,
+      collisionPolicy: 'overwrite',
+    });
+    console.log(`\n✓ Applied ${paths.length} file update${paths.length > 1 ? 's' : ''}.`);
+  }
+  const leftover = values.force ? [] : plan.files.changed;
+  if (leftover.length) {
+    const plural = leftover.length > 1;
+    console.log(
+      `\n${leftover.length} file${plural ? 's' : ''} ${plural ? 'differ' : 'differs'} from the current template and ` +
+        `${plural ? 'were' : 'was'} left untouched (they may be your edits):\n  ` +
+        leftover.join('\n  ') +
+        `\nReview them, then re-run with --force to overwrite the ones you want Packkit's version of.`,
+    );
+  }
+}
+
+function readName(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name;
+  } catch {
+    return null;
+  }
+}
+
+function report(plan, fromVersion, toVersion) {
+  console.log(`Packkit ${fromVersion} → ${toVersion}\n`);
+  const p = plan.packageJson;
+
+  if (plan.files.added.length) {
+    console.log(`New files (${plan.files.added.length}):\n  ` + plan.files.added.join('\n  '));
+  }
+  const addedDeps = Object.entries(p.addedDependencies);
+  const bumpedDeps = Object.entries(p.updatedDependencies);
+  if (addedDeps.length) {
+    console.log(`\nNew dependencies (${addedDeps.length}):\n  ` + addedDeps.map(([n, d]) => `${n}@${d.version} (${d.map})`).join('\n  '));
+  }
+  if (bumpedDeps.length) {
+    console.log(`\nDependency updates (${bumpedDeps.length}):\n  ` + bumpedDeps.map(([n, d]) => `${n}: ${d.from} → ${d.to}`).join('\n  '));
+  }
+  const addedScripts = Object.keys(p.addedScripts);
+  const changedScripts = Object.entries(p.changedScripts);
+  if (addedScripts.length) console.log(`\nNew scripts (${addedScripts.length}):\n  ` + addedScripts.join('\n  '));
+  if (changedScripts.length) {
+    console.log(`\nScript changes (${changedScripts.length}):\n  ` + changedScripts.map(([n, d]) => `${n}: ${d.from} → ${d.to}`).join('\n  '));
+  }
+  if (plan.files.changed.length) {
+    console.log(`\nFiles that differ — review before overwriting (${plan.files.changed.length}):\n  ` + plan.files.changed.join('\n  '));
+  }
+}

package/src/core/features/bundler.js

@@ -1,3 +1,4 @@
+import { V } from '../versions.js';
 // Always-on. Owns the package entry points (exports/main/module/types/files)
 // and the build tooling for the chosen bundler.
 
@@ -48,24 +49,24 @@ export default {
       files[`${tool}.config.${cfg.ext}`] = tsupConfig(cfg, entries, formats, tool);
       pkg.scripts.build = tool;
       pkg.scripts.dev = `${tool} --watch`;
-      pkg.devDependencies = { [tool]: tool === 'tsup' ? '^8.0.0' : '^0.6.0' };
+      pkg.devDependencies = { [tool]: tool === 'tsup' ? V.tsup : V.tsdown };
       // tsup/tsdown resolve `typescript` even for plain-JS builds; TS projects
       // already get it from the typescript feature.
-      if (!cfg.isTs) pkg.devDependencies.typescript = '^5.9.3';
+      if (!cfg.isTs) pkg.devDependencies.typescript = V.typescript;
     } else if (cfg.bundler === 'unbuild') {
       files['build.config.ts'] = unbuildConfig(cfg);
       pkg.scripts.build = 'unbuild';
       pkg.scripts.dev = 'unbuild --stub';
-      pkg.devDependencies = { unbuild: '^3.0.0' };
+      pkg.devDependencies = { unbuild: V.unbuild };
     } else if (cfg.bundler === 'rollup') {
       // Always a .js config — rollup can't load a .ts config without a loader.
       files['rollup.config.js'] = rollupConfig(cfg, formats);
       pkg.scripts.build = 'rollup -c';
       pkg.scripts.dev = 'rollup -c -w';
       pkg.devDependencies = {
-        rollup: '^4.0.0',
-        ...(cfg.isTs ? { '@rollup/plugin-typescript': '^12.0.0', tslib: '^2.6.0' } : {}),
-        ...(cfg.minify ? { '@rollup/plugin-terser': '^1.0.0' } : {}),
+        rollup: V.rollup,
+        ...(cfg.isTs ? { '@rollup/plugin-typescript': V['@rollup/plugin-typescript'], tslib: V.tslib } : {}),
+        ...(cfg.minify ? { '@rollup/plugin-terser': V['@rollup/plugin-terser'] } : {}),
       };
     } else if (cfg.bundler === 'none' && cfg.isTs) {
       // tsc-only build for TypeScript.
@@ -73,9 +74,14 @@ export default {
       pkg.scripts.dev = 'tsc --watch';
     }
 
+    // A service owns its `dev` script (tsx/node --watch on the server entry); the
+    // bundler only builds it. Don't also contribute a `dev` — that was a silent
+    // conflict the two features "resolved" purely by array order.
+    if (cfg.hasService) delete pkg.scripts.dev;
+
     if (build) pkg.scripts.prepublishOnly = pkg.scripts.build;
     pkg.scripts.clean = 'rimraf dist';
-    if (build) pkg.devDependencies = { ...pkg.devDependencies, rimraf: '^6.0.0' };
+    if (build) pkg.devDependencies = { ...pkg.devDependencies, rimraf: V.rimraf };
 
     return { files, pkg };
   },

package/src/core/features/checks.js

@@ -1,3 +1,4 @@
+import { V } from '../versions.js';
 // Package-correctness + hygiene checks (opt-in):
 //  - publint            validates package.json shape (exports/main/module)
 //  - are-the-types-wrong verifies TS consumers resolve your .d.ts correctly
@@ -14,12 +15,12 @@ export default {
       // node16 profile flags a "false" failure — use the esm-only profile.
       const attw = cfg.moduleFormat === 'esm' ? 'attw --pack --profile esm-only' : 'attw --pack';
       pkg.scripts['check:pkg'] = `publint && ${attw}`;
-      pkg.devDependencies.publint = '^0.3.0';
-      pkg.devDependencies['@arethetypeswrong/cli'] = '^0.18.0';
+      pkg.devDependencies.publint = V.publint;
+      pkg.devDependencies['@arethetypeswrong/cli'] = V['@arethetypeswrong/cli'];
     }
     if (cfg.knip) {
       pkg.scripts.knip = 'knip';
-      pkg.devDependencies.knip = '^5.0.0';
+      pkg.devDependencies.knip = V.knip;
     }
 
     return { files: {}, pkg };

package/src/core/features/env.js

@@ -1,3 +1,4 @@
+import { V } from '../versions.js';
 // Type-safe environment-variable validation for server-side runtimes (services
 // and CLIs). Validates process.env once at startup with a Zod schema, so a
 // misconfigured deploy fails fast with a clear message instead of a surprise
@@ -12,7 +13,7 @@ export default {
     files[`src/env.${cfg.ext}`] = cfg.isTs ? envTs() : envJs();
     files['.env.example'] = ['NODE_ENV=development', 'PORT=3000', ''].join('\n');
 
-    return { files, pkg: { dependencies: { zod: '^4.0.0' } } };
+    return { files, pkg: { dependencies: { zod: V.zod } } };
   },
 };
 

package/src/core/features/frameworks.js

@@ -1,3 +1,4 @@
+import { V, PEER } from '../versions.js';
 // React / Vue / Svelte source + dependencies, for both component libraries and
 // Vite apps. The Vite build wiring lives in vite.js; here we emit the source
 // files, the runtime deps (peer for libs, direct for apps), and — for Svelte
@@ -40,7 +41,7 @@ function react(cfg, files, pkg, forApp) {
       `}`,
       ``,
     ].join('\n');
-    pkg.dependencies = { react: '^19.0.0', 'react-dom': '^19.0.0' };
+    pkg.dependencies = { react: V.react, 'react-dom': V['react-dom'] };
   } else {
     files[`src/index.${x}`] = cfg.isTs
       ? [
@@ -55,13 +56,13 @@ function react(cfg, files, pkg, forApp) {
           ``,
         ].join('\n')
       : [`export function Button({ label, onClick }) {`, `\treturn <button onClick={onClick}>{label}</button>;`, `}`, ``].join('\n');
-    pkg.peerDependencies = { react: '>=18', 'react-dom': '>=18' };
-    pkg.devDependencies.react = '^19.0.0';
-    pkg.devDependencies['react-dom'] = '^19.0.0';
+    pkg.peerDependencies = { react: PEER.react, 'react-dom': PEER['react-dom'] };
+    pkg.devDependencies.react = V.react;
+    pkg.devDependencies['react-dom'] = V['react-dom'];
   }
   if (cfg.isTs) {
-    pkg.devDependencies['@types/react'] = '^19.0.0';
-    pkg.devDependencies['@types/react-dom'] = '^19.0.0';
+    pkg.devDependencies['@types/react'] = V['@types/react'];
+    pkg.devDependencies['@types/react-dom'] = V['@types/react-dom'];
   }
 }
 
@@ -78,7 +79,7 @@ function vue(cfg, files, pkg, forApp) {
       ``,
     ].join('\n');
     files['src/App.vue'] = [script, `</script>`, ``, `<template>`, `\t<h1>Hello from ${cfg.name}</h1>`, `</template>`, ``].join('\n');
-    pkg.dependencies = { vue: '^3.4.0' };
+    pkg.dependencies = { vue: V.vue };
   } else {
     files[`src/index.${cfg.ext}`] = `export { default as Button } from './Button.vue';\n`;
     files['src/Button.vue'] = [
@@ -91,8 +92,8 @@ function vue(cfg, files, pkg, forApp) {
       `</template>`,
       ``,
     ].join('\n');
-    pkg.peerDependencies = { vue: '>=3' };
-    pkg.devDependencies.vue = '^3.4.0';
+    pkg.peerDependencies = { vue: PEER.vue };
+    pkg.devDependencies.vue = V.vue;
   }
 }
 
@@ -101,8 +102,8 @@ function svelte(cfg, files, pkg, forApp) {
   const script = cfg.isTs ? `<script lang="ts">` : `<script>`;
   // Shared by the Vite app build and the Vitest (test) config; enables TS in SFCs.
   files['svelte.config.js'] = `import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';\n\nexport default { preprocess: vitePreprocess() };\n`;
-  pkg.devDependencies['@sveltejs/vite-plugin-svelte'] = '^7.0.0';
-  if (cfg.isTs) pkg.devDependencies['svelte-check'] = '^4.0.0';
+  pkg.devDependencies['@sveltejs/vite-plugin-svelte'] = V['@sveltejs/vite-plugin-svelte'];
+  if (cfg.isTs) pkg.devDependencies['svelte-check'] = V['svelte-check'];
   if (forApp) {
     files['index.html'] = htmlShell(cfg, `/src/main.${cfg.ext}`);
     files[`src/main.${cfg.ext}`] = [
@@ -114,7 +115,7 @@ function svelte(cfg, files, pkg, forApp) {
       ``,
     ].join('\n');
     files['src/App.svelte'] = [script, `</script>`, ``, `<h1>Hello from ${cfg.name}</h1>`, ``].join('\n');
-    pkg.dependencies = { svelte: '^5.0.0' };
+    pkg.dependencies = { svelte: V.svelte };
   } else {
     // Svelte libraries ship uncompiled source; the consumer's bundler compiles.
     files[`src/index.${cfg.ext}`] = `export { default as Button } from './Button.svelte';\n`;
@@ -127,8 +128,8 @@ function svelte(cfg, files, pkg, forApp) {
       `<button>{label}</button>`,
       ``,
     ].filter((l) => l !== ``).join('\n') + '\n';
-    pkg.peerDependencies = { svelte: '>=5' };
-    pkg.devDependencies.svelte = '^5.0.0';
+    pkg.peerDependencies = { svelte: PEER.svelte };
+    pkg.devDependencies.svelte = V.svelte;
     // Ship source; point consumers at it.
     pkg.svelte = `./src/index.${cfg.ext}`;
     pkg.exports = { '.': { svelte: `./src/index.${cfg.ext}`, default: `./src/index.${cfg.ext}` } };

package/src/core/features/githooks.js

@@ -1,3 +1,4 @@
+import { V } from '../versions.js';
 export default {
   id: 'githooks',
   active: (cfg) => cfg.gitHooks !== 'none',
@@ -21,31 +22,31 @@ export default {
     if (cfg.gitHooks === 'simple-git-hooks') {
       pkg['simple-git-hooks'] = { 'pre-commit': needsLintStaged ? 'npx lint-staged' : 'npm test' };
       pkg.scripts.prepare = 'simple-git-hooks';
-      pkg.devDependencies['simple-git-hooks'] = '^2.11.0';
+      pkg.devDependencies['simple-git-hooks'] = V['simple-git-hooks'];
     } else if (cfg.gitHooks === 'husky') {
       files['.husky/pre-commit'] = (needsLintStaged ? 'npx lint-staged\n' : 'npm test\n');
       pkg.scripts.prepare = 'husky';
-      pkg.devDependencies.husky = '^9.1.0';
+      pkg.devDependencies.husky = V.husky;
     } else if (cfg.gitHooks === 'lefthook') {
-      files['lefthook.yml'] = lefthookYml(cfg, staged);
+      files['lefthook.yml'] = lefthookYml(cfg);
       // `|| true` so `npm install` doesn't fail before `git init` — lefthook
       // (unlike husky/simple-git-hooks) errors hard without a .git directory.
       pkg.scripts.prepare = 'lefthook install || true';
-      pkg.devDependencies.lefthook = '^2.0.0';
+      pkg.devDependencies.lefthook = V.lefthook;
     }
 
     if (needsLintStaged) {
       pkg['lint-staged'] = staged;
       // 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';
+      pkg.devDependencies['lint-staged'] = V['lint-staged'];
     }
 
     return { files, pkg };
   },
 };
 
-function lefthookYml(cfg, staged) {
+function lefthookYml(cfg) {
   const cmd =
     cfg.lint === 'biome'
       ? 'biome check --write --no-errors-on-unmatched {staged_files}'

package/src/core/features/index.js

@@ -1,5 +1,12 @@
 // Feature registry. Order matters only for how package.json fragments merge
 // (later features deep-merge over earlier ones); files are keyed by path.
+//
+// Ordering contract: no two features may own the same file path or the same
+// package.json field for a given config. That invariant is enforced by
+// test/feature-registry.test.js across the whole config matrix, so ordering is
+// never load-bearing for correctness — if a new feature collides with an
+// existing one, the test fails rather than the winner being decided by position
+// here. Each feature declares a unique `id`, surfaced in collision diagnostics.
 
 import meta from './meta.js';
 import bundler from './bundler.js';

package/src/core/features/lint.js

@@ -1,4 +1,5 @@
 import { toJson } from '../render.js';
+import { V } from '../versions.js';
 
 export default {
   id: 'lint',
@@ -19,19 +20,19 @@ export default {
       files['.prettierignore'] = 'dist\ncoverage\n';
       pkg.scripts.format = 'prettier --write .';
       pkg.scripts['format:check'] = 'prettier --check .';
-      pkg.devDependencies.prettier = '^3.3.0';
+      pkg.devDependencies.prettier = V.prettier;
     }
 
     if (cfg.lint === 'eslint-prettier') {
       files['eslint.config.js'] = eslintFlatConfig(cfg);
       pkg.scripts.lint = 'eslint .';
       pkg.scripts['lint:fix'] = 'eslint . --fix';
-      pkg.devDependencies.eslint = '^10.0.0';
-      pkg.devDependencies['@eslint/js'] = '^10.0.0';
-      if (cfg.isTs) pkg.devDependencies['typescript-eslint'] = '^8.0.0';
+      pkg.devDependencies.eslint = V.eslint;
+      pkg.devDependencies['@eslint/js'] = V['@eslint/js'];
+      if (cfg.isTs) pkg.devDependencies['typescript-eslint'] = V['typescript-eslint'];
     } else if (cfg.lint === 'oxlint') {
       pkg.scripts.lint = 'oxlint';
-      pkg.devDependencies.oxlint = '^1.0.0';
+      pkg.devDependencies.oxlint = V.oxlint;
     } else if (cfg.lint === 'biome') {
       files['biome.json'] = toJson({
         $schema: 'https://biomejs.dev/schemas/2.1.2/schema.json',
@@ -42,7 +43,7 @@ export default {
       pkg.scripts.lint = 'biome lint .';
       pkg.scripts['lint:fix'] = 'biome lint --write .';
       pkg.scripts.format = 'biome format --write .';
-      pkg.devDependencies['@biomejs/biome'] = '^2.0.0';
+      pkg.devDependencies['@biomejs/biome'] = V['@biomejs/biome'];
     }
 
     return { files, pkg };