create-packkit 3.0.0 → 3.1.0

package/src/embedded/contract.js

@@ -13,15 +13,17 @@
 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 (cfg.hasService) {
+  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: cfg.hasBuild ? run('build') : undefined,
+      buildCommand: build.has ? run('build') : undefined,
       startCommand: start,
       port: 3000,
       healthCheckPath: '/health',
@@ -29,7 +31,7 @@ export function deriveDeploymentContract(cfg) {
     });
   }
 
-  if (cfg.hasApp) {
+  if (targets.app) {
     return prune({
       type: 'static',
       buildCommand: run('build'),
@@ -38,16 +40,16 @@ export function deriveDeploymentContract(cfg) {
     });
   }
 
-  if (cfg.hasCli) {
+  if (targets.cli) {
     return prune({
       type: 'cli',
-      buildCommand: cfg.hasBuild ? run('build') : undefined,
+      buildCommand: build.has ? run('build') : undefined,
     });
   }
 
   return prune({
     type: 'library',
-    buildCommand: cfg.hasBuild ? run('build') : undefined,
+    buildCommand: build.has ? run('build') : undefined,
   });
 }
 

package/src/embedded/index.js

@@ -24,6 +24,7 @@ import { analyzePkgFragments } from './pkg-merge.js';
 import { deriveDeploymentContract } from './contract.js';
 
 export { deriveDeploymentContract };
+export { planUpgrade, isUpgradeEmpty, buildUpgradeWrite } from './upgrade.js';
 
 // Bumped when the shape of PackkitProjectDefinition changes incompatibly.
 export const SCHEMA_VERSION = 2;
@@ -37,7 +38,7 @@ const MAX_DEFINITION_BYTES = 50_000_000;
 const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
 /** Non-OPTIONS config keys the pipeline sets itself; not "unknown". */
-const KNOWN_EXTRA_KEYS = new Set(['preset', 'generatorVersion']);
+const KNOWN_EXTRA_KEYS = new Set(['preset', 'generatorVersion', 'resolved']);
 
 // Fields where a host override silently changing an existing value is worth a
 // diagnostic (matches pkg-merge's protected set + dependency maps).
@@ -72,12 +73,18 @@ function packkitVersion() {
 }
 
 /**
- * Generate a complete project in memory. No files are written, nothing is
- * installed, no commands run. Returns a GeneratedProject with diagnostics.
+ * Resolve a preset + overrides into a complete, validated config, collecting
+ * the diagnostics normalization produced — without generating anything.
+ *
+ * Generation and resolution are split so a trusted caller (the CLI) can make
+ * decisions on the resolved config — a Node-floor check, creating the remote —
+ * and then generate, while a host app just uses createProject() which does both.
  * Throws PackkitValidationError if the config is fatally invalid.
+ *
+ * @returns {{ config: object, diagnostics: object[] }}
  */
-export function createProject(input = {}) {
-  if (!input || typeof input !== 'object') throw new TypeError('createProject expects an input object.');
+export function resolveProjectConfig(input = {}) {
+  if (!input || typeof input !== 'object') throw new TypeError('resolveProjectConfig expects an input object.');
 
   const merged = { ...(input.config || {}), ...(input.overrides || {}) };
   if (input.name != null) merged.name = input.name;
@@ -106,7 +113,36 @@ export function createProject(input = {}) {
   const raw = canonicalPreset
     ? { ...PRESETS[canonicalPreset], ...merged, preset: canonicalPreset }
     : merged;
-  const { config, files, summary, fileSources, fragments } = generateTracked({ ...raw, generatorVersion: packkitVersion() }, diagnostics);
+  const config = normalizeConfig({ ...raw, generatorVersion: packkitVersion() }, diagnostics);
+  return { config, diagnostics };
+}
+
+/**
+ * Generate a complete project in memory. No files are written, nothing is
+ * installed, no commands run. Returns a GeneratedProject with diagnostics.
+ * Throws PackkitValidationError if the config is fatally invalid.
+ */
+export function createProject(input = {}) {
+  const { config, diagnostics } = resolveProjectConfig(input);
+  return assembleProject(config, diagnostics);
+}
+
+/**
+ * Build a project from an already-resolved config (from resolveProjectConfig,
+ * possibly with a field like `repo` set since). For trusted callers only — the
+ * config is assumed valid; pass its resolution diagnostics through so they
+ * appear on the project. Re-normalizes idempotently.
+ */
+export function createProjectFromResolvedConfig(config, { diagnostics = [] } = {}) {
+  const resolved = normalizeConfig({ generatorVersion: packkitVersion(), ...config });
+  return assembleProject(resolved, [...diagnostics]);
+}
+
+// Shared generation core: turn a resolved config into a GeneratedProject,
+// appending collision and package-conflict diagnostics to whatever the caller
+// already collected during resolution.
+function assembleProject(config, diagnostics) {
+  const { files, summary, fileSources, fragments } = generateTracked(config);
 
   for (const [path, sources] of Object.entries(fileSources)) {
     if (sources.length > 1) {
@@ -236,8 +272,19 @@ export function exportProjectDefinition(project) {
   };
 }
 
-/** Rebuild a project from a stored definition, re-applying its extensions. */
-export function createProjectFromDefinition(definition) {
+/**
+ * Rebuild a project from a stored definition, re-applying its extensions.
+ *
+ * If a file the host originally *added* now collides with one the current
+ * Packkit generates, that's surfaced as an error-severity diagnostic. With
+ * `driftPolicy: 'error'` that condition throws instead — for a caller that
+ * wants an unreconciled definition to fail loudly rather than reproduce
+ * silently. The default, `'report'`, returns the project with the diagnostic.
+ */
+export function createProjectFromDefinition(definition, { driftPolicy = 'report' } = {}) {
+  if (!['report', 'error'].includes(driftPolicy)) {
+    throw new TypeError(`Unknown driftPolicy "${driftPolicy}".`);
+  }
   validateDefinition(definition);
   const current = packkitVersion();
   const base = createProject({ preset: definition.preset, config: definition.config });
@@ -278,6 +325,14 @@ export function createProjectFromDefinition(definition) {
     }
   }
 
+  // With driftPolicy: 'error', an unreconciled add-collision fails the rebuild
+  // rather than reproducing silently. Version drift alone (a warning) never
+  // throws — only the error-severity collision does.
+  const fatalDrift = drift.filter((d) => d.severity === 'error');
+  if (driftPolicy === 'error' && fatalDrift.length) {
+    throw new PackkitValidationError('The definition no longer reconciles with this Packkit version; see error.diagnostics.', fatalDrift);
+  }
+
   const hasExt = Object.keys(plainFiles).length || Object.keys(ext.packageJson || {}).length;
   // Carry the stored modes so re-exporting the replayed project preserves the
   // original add/replace intent rather than re-deriving it against this base.

package/src/embedded/upgrade.js

@@ -0,0 +1,148 @@
+// Upgrade planning.
+//
+// A project scaffolded by Packkit records what it came from in packkit.json.
+// That lets us regenerate the *current* recommended output and compare it to
+// what's on disk — so a project can be told what has drifted from Packkit's
+// current templates and choose what to pull in.
+//
+// This module is pure: it takes two file maps (freshly generated vs. on disk)
+// and returns a classified plan. Reading the disk and applying the plan live in
+// the CLI; keeping the decision logic here makes it testable and reusable.
+
+import { finalizePackageJson } from '../core/pkg.js';
+import { deepMerge, toJson } from '../core/render.js';
+
+// Files Packkit owns but that get structural, not whole-file, treatment.
+// package.json is co-owned (the host adds its own deps/scripts); packkit.json
+// is expected to change every version (it records the generator version).
+const STRUCTURAL = new Set(['package.json', 'packkit.json']);
+const DEP_MAPS = ['dependencies', 'devDependencies', 'peerDependencies'];
+
+/**
+ * Classify how a freshly-generated project differs from what's on disk.
+ *
+ * @param {object} input
+ * @param {Record<string,string>} input.generated  the current createProject().files
+ * @param {Record<string,string|undefined>} input.onDisk  the on-disk content for
+ *   each generated path (undefined when the file doesn't exist)
+ * @returns an upgrade plan: which files are new/changed/current, and the
+ *   structural package.json delta.
+ */
+export function planUpgrade({ generated, onDisk }) {
+  const added = [];
+  const changed = [];
+  const unchanged = [];
+
+  for (const [path, content] of Object.entries(generated)) {
+    if (STRUCTURAL.has(path)) continue;
+    const disk = onDisk[path];
+    if (disk === undefined) added.push(path);
+    else if (disk === content) unchanged.push(path);
+    else changed.push(path);
+  }
+
+  return {
+    files: {
+      added: added.sort(),
+      // "changed" means differs — could be a Packkit template change or the
+      // user's own edit. Without a stored baseline we can't tell which, so these
+      // are surfaced for review, never overwritten automatically.
+      changed: changed.sort(),
+      unchanged: unchanged.sort(),
+    },
+    packageJson: diffPackageJson(onDisk['package.json'], generated['package.json']),
+    // packkit.json records the generator version, so it always "changes" on an
+    // upgrade; applying the upgrade refreshes it.
+    provenanceOutdated: onDisk['packkit.json'] !== generated['packkit.json'],
+  };
+}
+
+/** True when a plan found nothing to bring in. */
+export function isUpgradeEmpty(plan) {
+  const p = plan.packageJson;
+  return (
+    plan.files.added.length === 0 &&
+    plan.files.changed.length === 0 &&
+    Object.keys(p.addedDependencies).length === 0 &&
+    Object.keys(p.updatedDependencies).length === 0 &&
+    Object.keys(p.addedScripts).length === 0 &&
+    Object.keys(p.changedScripts).length === 0 &&
+    !plan.provenanceOutdated
+  );
+}
+
+/**
+ * Build the { path: content } map to write for a plan. Always includes new
+ * files, the refreshed package.json (deps bumped / added, scripts added or
+ * updated — the user's own extras preserved), and packkit.json. Changed files
+ * are included only when `includeChanged` is set (an explicit overwrite).
+ */
+export function buildUpgradeWrite({ generated, onDisk, plan, includeChanged = false }) {
+  const out = {};
+  for (const path of plan.files.added) out[path] = generated[path];
+  if (includeChanged) for (const path of plan.files.changed) out[path] = generated[path];
+
+  if (onDisk['package.json'] && generated['package.json']) {
+    const merged = mergePackageJson(onDisk['package.json'], generated['package.json'], plan.packageJson);
+    if (merged !== onDisk['package.json']) out['package.json'] = merged;
+  }
+  if (plan.provenanceOutdated && generated['packkit.json']) out['packkit.json'] = generated['packkit.json'];
+  return out;
+}
+
+// Apply only the deps/scripts the plan flagged onto the on-disk package.json,
+// so a bump lands but the user's own additions and field ordering survive.
+function mergePackageJson(diskStr, genStr, pkgPlan) {
+  const disk = JSON.parse(diskStr);
+  const gen = JSON.parse(genStr);
+
+  const patch = {};
+  for (const [name, { map }] of Object.entries(pkgPlan.addedDependencies)) {
+    (patch[map] ||= {})[name] = gen[map][name];
+  }
+  for (const [name, { map }] of Object.entries(pkgPlan.updatedDependencies)) {
+    (patch[map] ||= {})[name] = gen[map][name];
+  }
+  const scripts = {};
+  for (const name of Object.keys(pkgPlan.addedScripts)) scripts[name] = gen.scripts[name];
+  for (const name of Object.keys(pkgPlan.changedScripts)) scripts[name] = gen.scripts[name];
+  if (Object.keys(scripts).length) patch.scripts = scripts;
+
+  return toJson(finalizePackageJson(deepMerge(disk, patch)));
+}
+
+// Structural package.json diff: what Packkit would add or bump, without ever
+// treating the user's own extra deps/scripts as "removed".
+function diffPackageJson(diskStr, genStr) {
+  const empty = { addedDependencies: {}, updatedDependencies: {}, addedScripts: {}, changedScripts: {} };
+  if (!diskStr || !genStr) return empty;
+
+  let disk;
+  let gen;
+  try {
+    disk = JSON.parse(diskStr);
+    gen = JSON.parse(genStr);
+  } catch {
+    return empty; // a hand-broken package.json — leave it alone
+  }
+
+  const addedDependencies = {};
+  const updatedDependencies = {};
+  for (const map of DEP_MAPS) {
+    for (const [name, version] of Object.entries(gen[map] || {})) {
+      const current = disk[map]?.[name];
+      if (current === undefined) addedDependencies[name] = { map, version };
+      else if (current !== version) updatedDependencies[name] = { map, from: current, to: version };
+    }
+  }
+
+  const addedScripts = {};
+  const changedScripts = {};
+  for (const [name, cmd] of Object.entries(gen.scripts || {})) {
+    const current = disk.scripts?.[name];
+    if (current === undefined) addedScripts[name] = cmd;
+    else if (current !== cmd) changedScripts[name] = { from: current, to: cmd };
+  }
+
+  return { addedDependencies, updatedDependencies, addedScripts, changedScripts };
+}

package/types/embedded.d.ts

@@ -85,8 +85,28 @@ export class PackkitValidationError extends Error {
 export const SCHEMA_VERSION: number;
 
 export function createProject(input?: CreateProjectInput): GeneratedProject;
+export function resolveProjectConfig(input?: CreateProjectInput): { config: ResolvedPackkitConfig; diagnostics: Diagnostic[] };
+export function createProjectFromResolvedConfig(config: ResolvedPackkitConfig, options?: { diagnostics?: Diagnostic[] }): GeneratedProject;
 export function extendProject(project: GeneratedProject, extension?: ProjectExtension): GeneratedProject;
 export function exportProjectDefinition(project: GeneratedProject): PackkitProjectDefinition;
-export function createProjectFromDefinition(definition: PackkitProjectDefinition): GeneratedProject;
+export function createProjectFromDefinition(
+  definition: PackkitProjectDefinition,
+  options?: { driftPolicy?: 'report' | 'error' },
+): GeneratedProject;
 export function calculateProjectDigest(project: GeneratedProject): string;
 export function deriveDeploymentContract(config: ResolvedPackkitConfig): DeploymentContract;
+
+export interface UpgradePlan {
+  files: { added: string[]; changed: string[]; unchanged: string[] };
+  packageJson: {
+    addedDependencies: Record<string, { map: string; version: string }>;
+    updatedDependencies: Record<string, { map: string; from: string; to: string }>;
+    addedScripts: Record<string, string>;
+    changedScripts: Record<string, { from: string; to: string }>;
+  };
+  provenanceOutdated: boolean;
+}
+
+export function planUpgrade(input: { generated: Record<string, string>; onDisk: Record<string, string | undefined> }): UpgradePlan;
+export function isUpgradeEmpty(plan: UpgradePlan): boolean;
+export function buildUpgradeWrite(input: { generated: Record<string, string>; onDisk: Record<string, string | undefined>; plan: UpgradePlan; includeChanged?: boolean }): Record<string, string>;