create-packkit 2.9.0 → 3.0.0

package/README.md

@@ -193,14 +193,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.0.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"

package/src/core/index.js

@@ -22,23 +22,49 @@ export function fromPreset(name, overrides = {}) {
   return cfg;
 }
 
-/** Turn a config into a complete set of files. */
-export function generate(input) {
-  const cfg = normalizeConfig(input);
-  if (cfg.monorepo) return buildMonorepo(cfg);
-
+/**
+ * Run every active feature, collecting its files and package.json fragment.
+ * Returns the raw material — file map, the fragments in contribution order,
+ * and which feature produced each file — so callers that need provenance (the
+ * embedded API's collision detection) get it without a second pass, while
+ * `generate` folds it into the same output as before.
+ */
+export function assemble(cfg) {
   const files = {};
+  const fileSources = {};
+  const fragments = [];
   let pkg = {};
 
   for (const feat of features) {
     if (!feat.active(cfg)) continue;
     const out = feat.apply(cfg) || {};
     if (out.files) {
-      for (const [path, contents] of Object.entries(out.files)) files[path] = contents;
+      for (const [path, contents] of Object.entries(out.files)) {
+        (fileSources[path] ||= []).push(feat.id);
+        files[path] = contents;
+      }
+    }
+    if (out.pkg) {
+      fragments.push({ source: feat.id, pkg: out.pkg });
+      pkg = deepMerge(pkg, out.pkg);
     }
-    if (out.pkg) pkg = deepMerge(pkg, out.pkg);
   }
+  return { files, fileSources, fragments, pkg };
+}
 
+/**
+ * Generate, keeping the provenance assemble() produced. One assembly pass feeds
+ * both the public files and the embedded API's conflict diagnostics, so the
+ * bytes callers get and the provenance they inspect come from the same run.
+ */
+export function generateTracked(input, diagnostics = null) {
+  const cfg = normalizeConfig(input, diagnostics);
+  if (cfg.monorepo) {
+    // The monorepo generator is a separate path with no per-feature fragments.
+    return { ...buildMonorepo(cfg), fileSources: {}, fragments: [] };
+  }
+
+  const { files, fileSources, fragments, pkg } = assemble(cfg);
   files['package.json'] = toJson(finalizePackageJson(pkg));
   files['packkit.json'] = provenance(cfg);
 
@@ -47,9 +73,17 @@ export function generate(input) {
     files,
     postCommands: postCommands(cfg),
     summary: summarize(cfg, files),
+    fileSources,
+    fragments,
   };
 }
 
+/** Turn a config into a complete set of files. */
+export function generate(input) {
+  const { config, files, postCommands, summary } = generateTracked(input);
+  return { config, files, postCommands, summary };
+}
+
 function postCommands(cfg) {
   const install = {
     npm: 'npm install',

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,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/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;
+}