create-packkit 2.8.0 → 3.0.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' },
@@ -54,6 +55,14 @@ export const OPTIONS = {
   monorepo: {
     group: 'core', type: 'boolean', label: 'Monorepo (pnpm/Turborepo workspace)', default: false,
   },
+  monorepoLayout: {
+    group: 'core', type: 'select', label: 'Monorepo layout', default: 'libraries',
+    when: (cfg) => cfg.monorepo,
+    choices: [
+      { value: 'libraries', label: 'Libraries — linked packages you publish' },
+      { value: 'fullstack', label: 'Full-stack app — web + server + shared' },
+    ],
+  },
   framework: {
     group: 'core', type: 'select', label: 'Framework', default: 'none',
     choices: [
@@ -209,6 +218,7 @@ export const OPTION_HELP = {
   moduleFormat: 'How the package is consumed. ESM-only (default) is the modern, leanest choice — Node 20.19+/22.12+ can `require()` ESM. Pick dual only if you must support older CJS-only consumers; cjs-only is rarely needed.',
   target: 'What you are building — mix and match: a library (importable package), a CLI (ships a bin), an HTTP service, or an app (Vite SPA).',
   serviceFramework: 'For the service target: Hono (fast, web-standard, tiny — default), Fastify (batteries-included, plugins, schema validation), or Express (ubiquitous, huge ecosystem).',
+  monorepoLayout: 'What the workspace contains. "libraries" gives linked packages you publish (Changesets). "fullstack" gives apps/web (React+Vite) + apps/server (Hono) + packages/shared, wired together, with the server serving the web build in production.',
   monorepo: 'Generate a pnpm + Turborepo workspace with two linked example packages and Changesets. Only worth it when ≥2 packages share code.',
   framework: 'UI framework for component libraries and apps: React, Vue, or Svelte (or none for a plain package).',
   packageManager: 'Which package manager the scripts, lockfile, and CI target: npm, pnpm, yarn, or bun.',
@@ -250,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' });
+    }
+  };
+
+  // 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');
 
-  // 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.
+  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';
@@ -274,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';
@@ -296,31 +327,31 @@ 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.');
   return cfg;
 }

package/src/core/presets.js

@@ -19,6 +19,10 @@ export const PRESETS = {
     release: 'none', workflows: ['ci'], deps: 'renovate', agents: true, vscode: true,
   },
   monorepo: { monorepo: true, language: 'ts', packageManager: 'pnpm' },
+  fullstack: {
+    monorepo: true, monorepoLayout: 'fullstack', language: 'ts', packageManager: 'pnpm',
+    framework: 'react', test: 'vitest', release: 'none', workflows: ['ci'],
+  },
   oss: {
     language: 'ts', target: ['library'], moduleFormat: 'esm', bundler: 'tsup',
     test: 'vitest', coverage: true, lint: 'eslint-prettier', gitHooks: 'simple-git-hooks',
@@ -53,6 +57,8 @@ export const PRESET_ALIASES = {
   slib: 'svelte-lib',
   sapp: 'svelte-app',
   svc: 'node-service',
+  fs: 'fullstack',
+  app: 'fullstack',
   service: 'node-service',
 };
 
@@ -78,6 +84,7 @@ export const PRESET_INFO = {
   'svelte-app': 'Svelte SPA — Vite dev server, build, Testing Library.',
   'node-service': 'Node HTTP service (Hono) — tsx dev, tsup build, Dockerfile.',
   monorepo: 'pnpm + Turborepo workspace — two example packages, Changesets, CI.',
+  fullstack: 'Full-stack monorepo — React+Vite web, Hono API, shared package; server serves the web build in production.',
   oss: 'Full open-source library — coverage, CodeQL, Codecov, Renovate, Changesets.',
   minimal: 'Bare TS library — tsup only, no tests/lint/CI.',
   full: 'Everything on — library + CLI, all workflows and extras.',

package/src/core/provenance.js

@@ -0,0 +1,35 @@
+// packkit.json — what this project was generated from.
+//
+// Packkit used to leave no trace, so a project couldn't answer "what did I
+// start from?", couldn't be diffed against a newer template, and had no upgrade
+// path. This records the answer next to the code.
+//
+// Only settings that differ from the defaults are stored, so the file reads as
+// the decisions someone actually made rather than a dump of every option. It is
+// deliberately free of timestamps and machine details: generation stays a pure
+// function of the config, so the same config always produces the same bytes.
+
+import { toJson } from './render.js';
+import { defaultConfig } from './options.js';
+
+// How this particular run was invoked, rather than what the project is.
+// Replaying a config shouldn't re-run someone else's `git init` or install.
+const TRANSIENT = new Set(['gitInit', 'install', 'generatorVersion', 'preset', 'name']);
+
+export function provenance(cfg) {
+  const defaults = defaultConfig();
+  const settings = {};
+  for (const [key, value] of Object.entries(cfg)) {
+    // Skip derived helpers (isTs, hasApp, ext…) — they aren't inputs.
+    if (!(key in defaults) || TRANSIENT.has(key)) continue;
+    if (JSON.stringify(value) !== JSON.stringify(defaults[key])) settings[key] = value;
+  }
+
+  return toJson({
+    $schema: 'https://danmat.github.io/create-packkit/packkit.schema.json',
+    generator: 'create-packkit',
+    ...(cfg.generatorVersion ? { version: cfg.generatorVersion } : {}),
+    ...(cfg.preset ? { preset: cfg.preset } : {}),
+    settings,
+  });
+}

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/embedded/contract.js

@@ -0,0 +1,64 @@
+// 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`;
+
+  if (cfg.hasService) {
+    // 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: cfg.hasBuild ? run('build') : undefined,
+      startCommand: start,
+      port: 3000,
+      healthCheckPath: '/health',
+      requiredEnvironmentVariables: [],
+    });
+  }
+
+  if (cfg.hasApp) {
+    return prune({
+      type: 'static',
+      buildCommand: run('build'),
+      // Vite's default build output.
+      outputDirectory: 'dist',
+    });
+  }
+
+  if (cfg.hasCli) {
+    return prune({
+      type: 'cli',
+      buildCommand: cfg.hasBuild ? run('build') : undefined,
+    });
+  }
+
+  return prune({
+    type: 'library',
+    buildCommand: cfg.hasBuild ? 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;
+}