create-packkit 2.9.0 → 3.1.0

package/src/core/options.js

@@ -36,6 +36,7 @@ export const OPTIONS = {
   },
   serviceFramework: {
     group: 'core', type: 'select', label: 'Service framework (HTTP service)', default: 'hono',
+    when: (cfg) => cfg.target?.includes('service'),
     choices: [
       { value: 'hono', label: 'Hono (fast, web-standard)' },
       { value: 'fastify', label: 'Fastify' },
@@ -259,21 +260,42 @@ export function defaultConfig() {
   return cfg;
 }
 
-/** Merge partial input over the defaults and coerce a few fields. */
-export function normalizeConfig(input = {}) {
+/**
+ * Merge partial input over the defaults and coerce a few fields.
+ *
+ * Pass a `diagnostics` array to have every coercion that overrides an
+ * explicitly-supplied value recorded there (the embedded API surfaces these so
+ * a host application learns when Packkit changed its requested config, instead
+ * of the change happening silently). Existing callers omit it and see identical
+ * behavior — the coercions run exactly the same either way.
+ */
+export function normalizeConfig(input = {}, diagnostics = null) {
   const cfg = { ...defaultConfig(), ...input };
+  const requested = new Set(Object.keys(input));
 
-  // A CLI target needs an executable build; JS `strict` isn't a thing, etc.
-  if (!Array.isArray(cfg.target) || cfg.target.length === 0) cfg.target = ['library'];
-  if (!Array.isArray(cfg.workflows)) cfg.workflows = [];
+  // Record a coercion only when it actually changes an explicitly-requested
+  // value — a field left at its default that "changes" to the same default is
+  // not news. Derived helper flags (isTs, hasApp…) go through plain assignment
+  // below; they are computed, not overrides, so they never emit a diagnostic.
+  const coerce = (field, value, code, message, severity = 'warning') => {
+    const same = JSON.stringify(cfg[field]) === JSON.stringify(value);
+    if (same) return;
+    const previousValue = cfg[field];
+    cfg[field] = value;
+    if (diagnostics && requested.has(field)) {
+      diagnostics.push({ severity, code, field, previousValue, resolvedValue: value, message, source: 'normalize' });
+    }
+  };
 
-  // Minify needs a bundler.
-  if (cfg.bundler === 'none') cfg.minify = false;
-  // Coverage only makes sense with a test runner that supports it.
-  if (cfg.test === 'none' || cfg.test === 'node') cfg.coverage = false;
-  // Codecov workflow implies coverage.
-  if (cfg.workflows.includes('codecov')) cfg.coverage = true;
-  // npm-publish + changesets are complementary; nothing to coerce, just noted.
+  // A target is required; default it if missing.
+  if (!Array.isArray(cfg.target) || cfg.target.length === 0) {
+    coerce('target', ['library'], 'TARGET_DEFAULTED', 'No target was given, so "library" was used.', 'info');
+  }
+  if (!Array.isArray(cfg.workflows)) coerce('workflows', [], 'WORKFLOWS_DEFAULTED', 'workflows was not a list, so it was reset to none.', 'info');
+
+  if (cfg.bundler === 'none') coerce('minify', false, 'MINIFY_REQUIRES_BUNDLER', 'Minify was disabled because no bundler produces output to minify.');
+  if (cfg.test === 'none' || cfg.test === 'node') coerce('coverage', false, 'COVERAGE_UNSUPPORTED_RUNNER', `Coverage was disabled because the "${cfg.test}" test runner does not report it.`);
+  if (cfg.workflows.includes('codecov')) coerce('coverage', true, 'COVERAGE_FORCED_BY_CODECOV', 'Coverage was enabled because the Codecov workflow requires it.', 'info');
 
   cfg.isReact = cfg.framework === 'react';
   cfg.isVue = cfg.framework === 'vue';
@@ -283,7 +305,7 @@ export function normalizeConfig(input = {}) {
   cfg.hasApp = cfg.target.includes('app');
   // A component-framework package that isn't an app is a library.
   if (cfg.hasFramework && !cfg.hasApp && !cfg.target.includes('library')) {
-    cfg.target = ['library', ...cfg.target];
+    coerce('target', ['library', ...cfg.target], 'TARGET_LIBRARY_ADDED', 'A "library" target was added because a component framework needs something to build.', 'info');
   }
 
   cfg.isTs = cfg.language === 'ts';
@@ -305,31 +327,54 @@ export function normalizeConfig(input = {}) {
   cfg.hasBuild = cfg.viteBuild || (!cfg.svelteLib && (cfg.bundler !== 'none' || cfg.isTs));
 
   // Apps aren't published packages.
-  if (cfg.hasApp) cfg.moduleFormat = 'esm';
+  if (cfg.hasApp) coerce('moduleFormat', 'esm', 'MODULE_FORMAT_FORCED_FOR_APP', 'An app is bundled, not published, so its module format is ESM.', 'info');
   cfg.hasEsm = cfg.moduleFormat === 'esm' || cfg.moduleFormat === 'dual';
   cfg.hasCjs = cfg.moduleFormat === 'cjs' || cfg.moduleFormat === 'dual';
 
   // Storybook only applies to component libraries.
-  if (!cfg.hasFramework || cfg.hasApp || !cfg.hasLibrary) cfg.storybook = false;
+  if (!cfg.hasFramework || cfg.hasApp || !cfg.hasLibrary) coerce('storybook', false, 'STORYBOOK_REQUIRES_COMPONENT_LIBRARY', 'Storybook was disabled because it only applies to a component library.');
 
   // Playwright E2E only applies to app targets.
-  if (!cfg.hasApp) cfg.e2e = false;
+  if (!cfg.hasApp) coerce('e2e', false, 'E2E_REQUIRES_APP', 'End-to-end tests were disabled because they only apply to an app target.');
 
   // A monorepo is its own generation path (see buildMonorepo); it has a build.
   if (cfg.monorepo) cfg.hasBuild = true;
 
   cfg.publishable = (cfg.hasLibrary || cfg.hasCli) && !cfg.hasApp && !cfg.hasService;
   // Package-correctness checks only make sense for a publishable package.
-  if (!cfg.publishable) cfg.pkgChecks = false;
+  if (!cfg.publishable) coerce('pkgChecks', false, 'PKG_CHECKS_REQUIRES_PUBLISHABLE', 'Package-correctness checks were disabled because this project is not published to npm.');
   // Sourcemaps + shipped source only matter for a published package.
-  if (!cfg.publishable) cfg.sourcemaps = false;
+  if (!cfg.publishable) coerce('sourcemaps', false, 'SOURCEMAPS_REQUIRES_PUBLISHABLE', 'Sourcemaps were disabled because this project is not published to npm.');
   // A bundle-size budget needs a published package with a built entry.
-  if (!(cfg.publishable && cfg.hasBuild)) cfg.sizeLimit = false;
+  if (!(cfg.publishable && cfg.hasBuild)) coerce('sizeLimit', false, 'SIZE_LIMIT_REQUIRES_BUILT_LIBRARY', 'The bundle-size budget was disabled because it needs a published package with a build.');
   // Env validation is for server-side runtimes (services / CLIs), not libs/apps.
-  if (!(cfg.hasService || cfg.hasCli)) cfg.env = false;
+  if (!(cfg.hasService || cfg.hasCli)) coerce('env', false, 'ENV_REQUIRES_SERVICE_OR_CLI', 'Env validation was disabled because it only applies to a service or CLI.');
   // Canary snapshots ride on the Changesets flow.
-  if (cfg.release !== 'changesets') cfg.canary = false;
+  if (cfg.release !== 'changesets') coerce('canary', false, 'CANARY_REQUIRES_CHANGESETS', 'Canary releases were disabled because they require the Changesets release flow.');
   // JSR is TypeScript-first, ESM, and for plain (non-framework) libraries.
-  if (!(cfg.isTs && cfg.hasLibrary && !cfg.hasFramework && !cfg.hasApp)) cfg.jsr = false;
+  if (!(cfg.isTs && cfg.hasLibrary && !cfg.hasFramework && !cfg.hasApp)) coerce('jsr', false, 'JSR_REQUIRES_PLAIN_TS_LIBRARY', 'JSR publishing was disabled because it applies only to a plain TypeScript library.');
+
+  cfg.resolved = resolvedView(cfg);
   return cfg;
 }
+
+/**
+ * A grouped, read-only view of the derived state — the same booleans the flat
+ * `cfg.has*`/`is*` flags expose, organized by concern. Consumers that prefer
+ * structured access (`cfg.resolved.targets.app`) can use it instead of
+ * re-interpreting raw selections; the flat flags remain for existing code.
+ *
+ * It is derived purely from the flags computed above, and test/invariants.test.js
+ * asserts the two never disagree and that the state is internally consistent —
+ * so the derived model can't silently contradict itself.
+ */
+function resolvedView(cfg) {
+  return {
+    targets: { library: cfg.hasLibrary, cli: cfg.hasCli, service: cfg.hasService, app: cfg.hasApp },
+    language: { typescript: cfg.isTs, ext: cfg.ext, srcExt: cfg.srcExt },
+    framework: { name: cfg.framework, react: cfg.isReact, vue: cfg.isVue, svelte: cfg.isSvelte, any: cfg.hasFramework },
+    build: { vite: cfg.viteBuild, custom: cfg.customBuild, usesVite: cfg.usesVite, has: cfg.hasBuild },
+    module: { format: cfg.moduleFormat, esm: cfg.hasEsm, cjs: cfg.hasCjs },
+    package: { publishable: cfg.publishable, monorepo: cfg.monorepo },
+  };
+}

package/src/core/render.js

@@ -9,6 +9,11 @@ export function render(template, vars = {}) {
   });
 }
 
+// Keys that would let a merged-in object reach an object's prototype. The
+// embedded API deep-merges host-supplied data (extension package.json), so
+// these are skipped defensively even though the merge is immutable.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
 /** Deep-merge plain objects (arrays are concatenated + de-duped). Used to fold
  *  each feature's package.json fragment into the accumulator. */
 export function deepMerge(target, source) {
@@ -18,6 +23,7 @@ export function deepMerge(target, source) {
   if (isPlainObject(target) && isPlainObject(source)) {
     const out = { ...target };
     for (const [k, v] of Object.entries(source)) {
+      if (UNSAFE_KEYS.has(k)) continue;
       out[k] = k in target ? deepMerge(target[k], v) : v;
     }
     return out;

package/src/core/versions.js

@@ -0,0 +1,121 @@
+// The single source of truth for every dependency version Packkit writes into
+// generated projects. Feature modules reference these by name instead of
+// hard-coding a spec, so a bump happens in one place and the freshness workflow
+// (scripts/check-template-deps.mjs) has one authoritative list to check.
+//
+// A conformance test (test/versions.test.js) asserts that every version in the
+// generated output comes from this catalog, so nothing can drift back into a
+// feature module unnoticed.
+//
+// When you bump anything here, update LAST_REVIEWED.
+
+export const LAST_REVIEWED = '2026-07-26';
+
+// name → npm spec. Deps that ship at one version everywhere.
+export const V = {
+  // toolchain
+  typescript: '^5.9.3',
+  'typescript-eslint': '^8.0.0',
+  eslint: '^10.0.0',
+  '@eslint/js': '^10.0.0',
+  prettier: '^3.3.0',
+  '@biomejs/biome': '^2.0.0',
+  oxlint: '^1.0.0',
+  turbo: '^2.0.0',
+  rimraf: '^6.0.0',
+  '@types/node': '^24.0.0',
+
+  // build
+  tsup: '^8.0.0',
+  tsdown: '^0.6.0',
+  unbuild: '^3.0.0',
+  rollup: '^4.0.0',
+  '@rollup/plugin-typescript': '^12.0.0',
+  '@rollup/plugin-terser': '^1.0.0',
+  tslib: '^2.6.0',
+  tsx: '^4.0.0',
+  vite: '^8.0.0',
+  'vite-plugin-dts': '^5.0.0',
+
+  // test
+  vitest: '^4.0.0',
+  '@vitest/coverage-v8': '^4.0.0',
+  jsdom: '^29.0.0',
+  jest: '^30.0.0',
+  '@types/jest': '^30.0.0',
+  'ts-jest': '^29.0.0',
+  supertest: '^7.0.0',
+  '@types/supertest': '^6.0.0',
+  '@playwright/test': '^1.50.0',
+
+  // release / package checks
+  '@changesets/cli': '^2.27.0',
+  'release-it': '^21.0.0',
+  np: '^12.0.0',
+  publint: '^0.3.0',
+  '@arethetypeswrong/cli': '^0.18.0',
+  knip: '^5.0.0',
+  'size-limit': '^11.0.0',
+  '@size-limit/preset-small-lib': '^11.0.0',
+
+  // git hooks
+  'simple-git-hooks': '^2.11.0',
+  husky: '^9.1.0',
+  lefthook: '^2.0.0',
+  'lint-staged': '^16.2.0',
+
+  // react
+  react: '^19.0.0',
+  'react-dom': '^19.0.0',
+  '@types/react': '^19.0.0',
+  '@types/react-dom': '^19.0.0',
+  '@vitejs/plugin-react': '^6.0.0',
+  '@testing-library/react': '^16.0.0',
+  '@testing-library/dom': '^10.0.0',
+
+  // vue
+  vue: '^3.4.0',
+  'vue-tsc': '^3.0.0',
+  '@vitejs/plugin-vue': '^6.0.0',
+  '@testing-library/vue': '^8.1.0',
+
+  // svelte
+  svelte: '^5.0.0',
+  'svelte-check': '^4.0.0',
+  '@sveltejs/vite-plugin-svelte': '^7.0.0',
+  '@testing-library/svelte': '^5.2.0',
+
+  // storybook
+  storybook: '^10.0.0',
+  '@storybook/react': '^10.0.0',
+  '@storybook/react-vite': '^10.0.0',
+  '@storybook/vue3': '^10.0.0',
+  '@storybook/vue3-vite': '^10.0.0',
+  '@storybook/svelte': '^10.0.0',
+  '@storybook/svelte-vite': '^10.0.0',
+
+  // services
+  hono: '^4.5.0',
+  '@hono/node-server': '^2.0.0',
+  fastify: '^5.0.0',
+  express: '^5.0.0',
+  '@types/express': '^5.0.0',
+  zod: '^4.0.0',
+};
+
+// Peer-dependency ranges — deliberately looser than the direct-dependency spec,
+// so a component library declares broad compatibility rather than a hard pin.
+export const PEER = {
+  react: '>=18',
+  'react-dom': '>=18',
+  vue: '>=3',
+  svelte: '>=5',
+};
+
+// Deps intentionally held below their latest major, with the reason. The
+// freshness check reads this so a held-back dep is reported, not failed.
+export const HELD = {
+  typescript: 'typescript-eslint peers typescript <6.1.0 (no TS 7 support yet)',
+  knip: 'v6 crashes on the oxc-parser native binding',
+  'lint-staged': 'v17 requires Node >=22.22.1, above our Node 22 engines floor; hold at 16 to keep the Maintenance-LTS line working',
+};

package/src/embedded/contract.js

@@ -0,0 +1,66 @@
+// Provider-neutral deployment contract.
+//
+// A host application deploying a generated project needs to know how to build
+// and run it — but Packkit must not know or care whether that host is Vercel,
+// a Kubernetes cluster, or a Raspberry Pi. So this describes build/runtime
+// requirements in provider-agnostic terms, derived purely from the resolved
+// config. No AWS/Netlify/Vercel/Cloudflare/GitHub fields, by design.
+
+/**
+ * Derive the deployment contract from a resolved config.
+ * @returns {import('./index.js').DeploymentContract}
+ */
+export function deriveDeploymentContract(cfg) {
+  const run = (script) => (cfg.packageManager === 'npm' ? `npm run ${script}` : `${cfg.packageManager} ${script}`);
+  const start = cfg.packageManager === 'npm' ? 'npm start' : `${cfg.packageManager} start`;
+  // Read the structured resolved view rather than re-interpreting raw selections.
+  const { targets, build } = cfg.resolved;
+
+  if (targets.service) {
+    // The generated server reads PORT but defaults to 3000, so PORT is optional,
+    // not required — `port` communicates the default and the `PORT` env var
+    // overrides it. `healthCheckPath` is only asserted because every service
+    // framework Packkit generates (Hono/Fastify/Express) defines /health.
+    return prune({
+      type: 'node-service',
+      buildCommand: build.has ? run('build') : undefined,
+      startCommand: start,
+      port: 3000,
+      healthCheckPath: '/health',
+      requiredEnvironmentVariables: [],
+    });
+  }
+
+  if (targets.app) {
+    return prune({
+      type: 'static',
+      buildCommand: run('build'),
+      // Vite's default build output.
+      outputDirectory: 'dist',
+    });
+  }
+
+  if (targets.cli) {
+    return prune({
+      type: 'cli',
+      buildCommand: build.has ? run('build') : undefined,
+    });
+  }
+
+  return prune({
+    type: 'library',
+    buildCommand: build.has ? run('build') : undefined,
+  });
+}
+
+// Drop undefined fields and empty required-env arrays so the contract stays
+// minimal and deterministic — the same config always yields the same object.
+function prune(contract) {
+  const out = {};
+  for (const [k, v] of Object.entries(contract)) {
+    if (v === undefined) continue;
+    if (k === 'requiredEnvironmentVariables' && Array.isArray(v) && v.length === 0) continue;
+    out[k] = v;
+  }
+  return out;
+}