create-packkit 2.9.0 → 3.0.0

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,92 @@
+// 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 extendProject(project: GeneratedProject, extension?: ProjectExtension): GeneratedProject;
+export function exportProjectDefinition(project: GeneratedProject): PackkitProjectDefinition;
+export function createProjectFromDefinition(definition: PackkitProjectDefinition): GeneratedProject;
+export function calculateProjectDigest(project: GeneratedProject): string;
+export function deriveDeploymentContract(config: ResolvedPackkitConfig): DeploymentContract;

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>;