create-packkit 2.9.0 → 3.1.0

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

@@ -0,0 +1,151 @@
+// Controlled filesystem output for a GeneratedProject.
+//
+// This is the only place the embedded API touches disk, and it does nothing
+// else: no install, no git, no lifecycle scripts, no command execution. Every
+// path is validated again here — not just when the project was built — and the
+// real on-disk path is checked for symlinks, so a project that reached this
+// boundary from an untrusted source still can't escape the destination.
+
+import { mkdir, writeFile, stat, lstat } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { validateRelativePath } from './paths.js';
+
+export class PackkitWriteError extends Error {
+  constructor(message, { code, path, destination, cause } = {}) {
+    super(message);
+    this.name = 'PackkitWriteError';
+    this.code = code;
+    if (path !== undefined) this.path = path;
+    if (destination !== undefined) this.destination = destination;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/**
+ * Write a project's files under `destination`. Returns a WriteResult; never
+ * installs, inits git, or runs anything. Validates and preflights everything
+ * before the first write, so a bad file map or a policy collision fails cleanly
+ * rather than leaving a half-written project.
+ *
+ * @param {{ project: object, destination: string, collisionPolicy?: 'error'|'skip'|'overwrite' }} input
+ */
+export async function writeGeneratedProject(input) {
+  const { project, destination, collisionPolicy = 'error' } = input || {};
+  if (!project || typeof project !== 'object' || !project.files) {
+    throw new TypeError('writeGeneratedProject needs a project with a files map.');
+  }
+  if (typeof destination !== 'string' || destination.length === 0) {
+    throw new TypeError('A destination path is required.');
+  }
+  if (!['error', 'skip', 'overwrite'].includes(collisionPolicy)) {
+    throw new TypeError(`Unknown collisionPolicy "${collisionPolicy}".`);
+  }
+
+  const root = resolve(destination);
+  const prefix = root.endsWith(sep) ? root : root + sep;
+
+  // A symlinked destination could redirect the whole write outside where the
+  // caller thinks it's going. Reject it — a host that truly wants this can
+  // resolve the real path itself before calling.
+  await assertNotSymlink(root, false, root, root);
+
+  // 1) Lexical validation: any traversal/absolute path means we write nothing.
+  const planned = [];
+  for (const [path, contents] of Object.entries(project.files)) {
+    const res = validateRelativePath(path);
+    if (!res.ok) {
+      throw new PackkitWriteError(`Refusing to write invalid path "${path}": ${res.message}`, { code: res.code, path, destination: root });
+    }
+    const target = join(root, res.normalized);
+    if (target !== root && !target.startsWith(prefix)) {
+      throw new PackkitWriteError(`Refusing to write outside the destination: "${path}"`, { code: 'PATH_ESCAPE', path, destination: root });
+    }
+    planned.push({ path: res.normalized, target, contents });
+  }
+
+  // 2) Symlink + collision preflight against the real filesystem, before any
+  // write. Under the 'error' policy, one existing target aborts the whole
+  // operation with every collision listed — no partial output.
+  const collisions = [];
+  for (const { path, target } of planned) {
+    await assertNoSymlinkComponents(root, target, path);
+    if (await exists(target)) {
+      if (collisionPolicy === 'error') collisions.push(path);
+    }
+  }
+  if (collisions.length) {
+    throw new PackkitWriteError(
+      `Refusing to overwrite existing file(s): ${collisions.join(', ')}`,
+      { code: 'FILE_EXISTS', destination: root },
+    );
+  }
+
+  // 3) Write.
+  const writtenFiles = [];
+  const skippedFiles = [];
+  const diagnostics = [];
+  for (const { path, target, contents } of planned) {
+    try {
+      if ((collisionPolicy === 'skip') && (await exists(target))) {
+        skippedFiles.push(path);
+        diagnostics.push({ severity: 'info', code: 'FILE_SKIPPED', field: path, message: `"${path}" already existed and was left in place.`, source: 'writer' });
+        continue;
+      }
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, contents);
+      writtenFiles.push(path);
+    } catch (err) {
+      // A real filesystem failure on one file: record it, keep going, so the
+      // caller sees exactly what landed and what didn't.
+      diagnostics.push({ severity: 'error', code: 'WRITE_FAILED', field: path, message: `Could not write "${path}": ${err.message}`, source: 'writer' });
+    }
+  }
+
+  return { destination: root, writtenFiles, skippedFiles, diagnostics };
+}
+
+// Reject any existing symlink among the path components from root to target,
+// including the target itself — a lexical containment check can't catch
+// `dest/link -> /elsewhere`, but following real inodes can. Writing through an
+// existing symlink (even the final file, under 'overwrite') would escape.
+async function assertNoSymlinkComponents(root, target, path) {
+  const rel = target.slice(root.length + 1);
+  if (!rel) return;
+  const segments = rel.split(sep);
+  let current = root;
+  for (let i = 0; i < segments.length; i++) {
+    current = join(current, segments[i]);
+    const isFinal = i === segments.length - 1;
+    await assertNotSymlink(current, isFinal, path, root);
+  }
+}
+
+async function assertNotSymlink(component, isFinal, path, destination) {
+  try {
+    const info = await lstat(component);
+    if (info.isSymbolicLink()) {
+      throw new PackkitWriteError(`Refusing to write through a symbolic link: "${component}"`, { code: 'SYMLINK_PATH', path, destination });
+    }
+    // Intermediate components must be directories; the final one may already
+    // exist as a regular file (collision handling decides what to do with it).
+    if (!info.isDirectory() && !isFinal) {
+      throw new PackkitWriteError(`A parent path component is not a directory: "${component}"`, { code: 'PARENT_NOT_DIRECTORY', path, destination });
+    }
+  } catch (err) {
+    if (err instanceof PackkitWriteError) throw err;
+    if (err.code === 'ENOENT') return; // doesn't exist yet; nothing to follow
+    throw new PackkitWriteError(`Could not inspect "${component}": ${err.message}`, { code: 'STAT_FAILED', path, destination, cause: err });
+  }
+}
+
+// Only ENOENT means "not there" — permission and I/O errors are real problems
+// and must surface, not be silently read as a missing file.
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw new PackkitWriteError(`Could not stat "${p}": ${err.message}`, { code: 'STAT_FAILED', cause: err });
+  }
+}

package/src/index.js

@@ -0,0 +1,12 @@
+// Package root. Re-exports the pure generation core plus the Node embedded API,
+// so `import { generate, createProject, writeGeneratedProject } from 'create-packkit'`
+// works for host applications.
+//
+// The browser configurator does NOT import this file — it bundles
+// src/core/index.js directly (see build:web) — so pulling the Node-only
+// embedded modules in here doesn't affect browser compatibility of the core.
+// Consumers who want the core in isolation can import 'create-packkit/core'.
+
+export * from './core/index.js';
+export * from './embedded/index.js';
+export { writeGeneratedProject, PackkitWriteError } from './embedded/writer.js';

package/types/core.d.ts

@@ -0,0 +1,96 @@
+// Public types for the pure generation core.
+
+export type Language = 'ts' | 'js';
+export type ModuleFormat = 'esm' | 'dual' | 'cjs';
+export type Framework = 'none' | 'react' | 'vue' | 'svelte';
+export type Target = 'library' | 'cli' | 'service' | 'app';
+export type Bundler = 'tsup' | 'tsdown' | 'unbuild' | 'rollup' | 'none';
+export type TestRunner = 'vitest' | 'jest' | 'node' | 'none';
+export type Linter = 'eslint-prettier' | 'biome' | 'oxlint' | 'none';
+export type ReleaseTool = 'changesets' | 'release-it' | 'np' | 'none';
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+
+/** User-facing configuration. All fields optional on input; a preset or the
+ *  defaults fill the rest. */
+export interface PackkitConfig {
+  name?: string;
+  description?: string;
+  author?: string;
+  keywords?: string;
+  repo?: string;
+  language?: Language;
+  moduleFormat?: ModuleFormat;
+  framework?: Framework;
+  target?: Target[];
+  serviceFramework?: 'hono' | 'fastify' | 'express';
+  monorepo?: boolean;
+  monorepoLayout?: 'libraries' | 'fullstack';
+  packageManager?: PackageManager;
+  nodeVersion?: string;
+  bundler?: Bundler;
+  minify?: boolean;
+  test?: TestRunner;
+  coverage?: boolean;
+  storybook?: boolean;
+  e2e?: boolean;
+  sourcemaps?: boolean;
+  env?: boolean;
+  canary?: boolean;
+  pkgChecks?: boolean;
+  knip?: boolean;
+  sizeLimit?: boolean;
+  doctor?: boolean;
+  lint?: Linter;
+  gitHooks?: 'simple-git-hooks' | 'husky' | 'lefthook' | 'none';
+  release?: ReleaseTool;
+  jsr?: boolean;
+  workflows?: string[];
+  deps?: 'renovate' | 'dependabot' | 'none';
+  license?: string;
+  community?: boolean;
+  agents?: boolean;
+  vscode?: boolean;
+  editorconfig?: boolean;
+  gitInit?: boolean;
+  install?: boolean;
+  [key: string]: unknown;
+}
+
+/** The config after normalization: every field resolved, plus derived flags. */
+export interface ResolvedPackkitConfig extends PackkitConfig {
+  isTs: boolean;
+  isReact: boolean;
+  isVue: boolean;
+  isSvelte: boolean;
+  hasFramework: boolean;
+  hasApp: boolean;
+  hasLibrary: boolean;
+  hasCli: boolean;
+  hasService: boolean;
+  hasBuild: boolean;
+  publishable: boolean;
+  preset?: string;
+}
+
+export interface ProjectSummary {
+  name: string;
+  fileCount: number;
+  stack: string[];
+  workflows: string[];
+}
+
+export interface GenerateResult {
+  config: ResolvedPackkitConfig;
+  files: Record<string, string>;
+  postCommands: string[];
+  summary: ProjectSummary;
+}
+
+export function generate(input?: PackkitConfig): GenerateResult;
+export function fromPreset(name: string, overrides?: PackkitConfig): ResolvedPackkitConfig;
+export function normalizeConfig(input?: PackkitConfig, diagnostics?: unknown[]): ResolvedPackkitConfig;
+export function resolvePreset(name: string): string | undefined;
+
+export const OPTIONS: Record<string, unknown>;
+export const PRESET_NAMES: string[];
+export const PRESET_ALIASES: Record<string, string>;

package/types/embedded.d.ts

@@ -0,0 +1,112 @@
+// Public types for the embedded API (create-packkit/embedded).
+
+import type { PackkitConfig, ResolvedPackkitConfig, ProjectSummary } from './core.js';
+
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+
+export interface Diagnostic {
+  severity: DiagnosticSeverity;
+  code: string;
+  message: string;
+  field?: string;
+  source?: string;
+  previousValue?: unknown;
+  resolvedValue?: unknown;
+}
+
+export interface GeneratedProjectMetadata {
+  packkitVersion: string;
+  schemaVersion: number;
+  preset?: string;
+  generatedAt?: string;
+  extension?: Record<string, unknown>;
+}
+
+export type DeploymentType = 'static' | 'node-service' | 'library' | 'cli';
+
+export interface DeploymentContract {
+  type: DeploymentType;
+  buildCommand?: string;
+  outputDirectory?: string;
+  startCommand?: string;
+  port?: number;
+  healthCheckPath?: string;
+  requiredEnvironmentVariables?: string[];
+}
+
+export interface GeneratedProject {
+  config: ResolvedPackkitConfig;
+  files: Record<string, string>;
+  summary: ProjectSummary;
+  diagnostics: Diagnostic[];
+  metadata: GeneratedProjectMetadata;
+  deploymentContract: DeploymentContract;
+}
+
+export interface CreateProjectInput {
+  name?: string;
+  preset?: string;
+  config?: PackkitConfig;
+  overrides?: PackkitConfig;
+}
+
+export type CollisionPolicy = 'error' | 'skip' | 'overwrite';
+
+export interface ProjectExtension {
+  files?: Record<string, string>;
+  packageJson?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  collisionPolicy?: CollisionPolicy;
+}
+
+/** How a stored extension file relates to generated output: `add` = the host
+ *  introduced a new path; `replace` = it deliberately overrode a generated one. */
+export interface StoredExtensionFile {
+  content: string;
+  mode: 'add' | 'replace';
+}
+
+export interface PackkitProjectDefinition {
+  schemaVersion: number;
+  packkitVersion: string;
+  preset?: string;
+  config: PackkitConfig;
+  extensions?: {
+    files?: Record<string, StoredExtensionFile>;
+    packageJson?: Record<string, unknown>;
+  };
+}
+
+export class PackkitValidationError extends Error {
+  readonly code: 'PACKKIT_VALIDATION_FAILED';
+  diagnostics: Diagnostic[];
+}
+
+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,
+  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>;

package/types/index.d.ts

@@ -0,0 +1,6 @@
+// Package root types: the generation core plus the Node embedded API.
+
+export * from './core.js';
+export * from './embedded.js';
+export { writeGeneratedProject, PackkitWriteError } from './writer.js';
+export type { WriteGeneratedProjectInput, WriteResult } from './writer.js';

package/types/writer.d.ts

@@ -0,0 +1,25 @@
+// Public types for the writer (create-packkit/writer).
+
+import type { GeneratedProject, Diagnostic, CollisionPolicy } from './embedded.js';
+
+export interface WriteGeneratedProjectInput {
+  project: GeneratedProject;
+  destination: string;
+  collisionPolicy?: CollisionPolicy;
+}
+
+export interface WriteResult {
+  destination: string;
+  writtenFiles: string[];
+  skippedFiles: string[];
+  diagnostics: Diagnostic[];
+}
+
+export class PackkitWriteError extends Error {
+  code: string;
+  path?: string;
+  destination?: string;
+  cause?: unknown;
+}
+
+export function writeGeneratedProject(input: WriteGeneratedProjectInput): Promise<WriteResult>;