Embedded project-generation API (3.0.0)

[DanMat]

Adds a stable, typed, side-effect-free API so a Node application can use Packkit as a project-generation engine. Generate in memory, layer on your own deployment files, write to disk when ready — no prompts, installs, git, network, or command execution anywhere in the path.

This is the 3.0.0 feature. It's additive; nothing existing changes behavior.

The flow (acceptance criteria, verified)

import { createProject, extendProject, writeGeneratedProject } from 'create-packkit/embedded';
import { exportProjectDefinition, createProjectFromDefinition, calculateProjectDigest } from 'create-packkit/embedded';

const project   = createProject({ preset: 'react-app', name: 'example-app' });
const extended  = extendProject(project, { files: { '.github/workflows/deploy.yml': deployYaml } });
const recreated = createProjectFromDefinition(exportProjectDefinition(extended));

assert.equal(calculateProjectDigest(extended), calculateProjectDigest(recreated)); // ✓
await writeGeneratedProject({ project: recreated, destination: tmp });            // ✓

The written project then installs, builds, tests, and lints green — confirmed for ts-lib, cli, react-app, and node-service.

What's in it

Concern	API
Generate in memory	createProject(input) → GeneratedProject
Add host files (immutable)	extendProject(project, ext) — collision policy, default error
Write to disk (only side effect)	writeGeneratedProject({project, destination})
Reproduce later	exportProjectDefinition / createProjectFromDefinition
Change detection	calculateProjectDigest
Provider-neutral deploy info	deriveDeploymentContract

Design decisions worth a look

Normalization stops being silent. normalizeConfig now optionally records every coercion — Storybook disabled for a non-component-library, a size budget dropped for an unpublished package — as a Diagnostic with previousValue/resolvedValue. This is one of the architecture-review P1 items, landed here because the embedded API needed it. Fully backward compatible: callers that pass no collector get byte-identical behavior, which is why all 49 existing tests are untouched.

One generation path, with provenance. Rather than fork generation, generate() now delegates to a new assemble() that tracks which feature produced each file and fragment. generate()'s output is unchanged; the embedded layer reads the provenance to report file- and package.json-field conflicts.

Path safety is enforced twice — when a project is assembled and again at the writer boundary — so a project that reached the writer from an untrusted source still can't escape the destination. Rejects absolute, .., null-byte, Windows-reserved, and case-insensitive-colliding paths. An invalid path fails the whole write before anything lands.

Root export moved to src/index.js (core + embedded) so import { createProject } from 'create-packkit' works, per the brief's primary example. ./core stays the browser-safe core-only entry, and the web bundle builds from src/core directly, so browser compatibility is unaffected. Additive for existing consumers.

Types

Full .d.ts for the public surface (types/), a types entry in package.json, and per-export types. Packed-tarball tests confirm every export resolves from a clean install, the declarations ship, and the CLI still works.

Tests

23 new (unit + filesystem): resolution, diagnostics, unknown/invalid options, extension immutability, collisions, path traversal, determinism, definition round-trip, deployment contracts, and the writer (nested paths, Unicode/space filenames, collision policies, traversal rejection, no-install/no-git). Integration harness gains --embedded, wired into CI for four presets. 72 tests pass locally.

Explicitly out of scope (by the brief)

No cloud provisioning, repo creation, auth, infra, or provider SDKs. The deployment contract is provider-neutral — no AWS/Vercel/Netlify/Cloudflare/GitHub fields. The core generation path stays free of network calls.

Docs: docs/EMBEDDING.md.

🤖 Generated with Claude Code

[DanMat]

Thanks — thorough review. Everything in Fix before merge and Strongly preferred is addressed in the latest commit. Rundown:

Blockers

1. Symlink traversal — the writer now follows real inodes and rejects a symbolic link at any component between the destination and the target, including the final file (closing the overwrite-through-symlink case) and a symlinked destination itself. SYMLINK_PATH / PARENT_NOT_DIRECTORY. Tests: dest/link -> outside and a symlinked destination.
2. Definition replay — each stored extension file now carries mode: 'add' | 'replace'. On replay under a newer Packkit, an original add that now collides with a generated file is surfaced as an error-severity EXTENSION_ADD_COLLIDES_WITH_NEW_BASE diagnostic rather than silently overwriting; the stored copy still reproduces, so the definition remains a faithful contract while the drift is visible. SCHEMA_VERSION → 2.

Also fixed

3. Dependency conflicts keyed by section+name — dependencies.react vs peerDependencies.react at different ranges is no longer a false conflict; a real same-section disagreement still is.
4. exists()/lstat only treat ENOENT as absent — permission/I/O errors surface as STAT_FAILED instead of masquerading as a missing file.
5. Extension file content validated as string up front (INVALID_FILE_CONTENT).
6. Host package overrides reported — EXTENSION_PACKAGE_FIELD_OVERRIDE / EXTENSION_DEPENDENCY_VERSION_OVERRIDE; the host still wins, visibly.
7. Collision preflight — under the error policy the writer collects every existing target and aborts before writing anything (no partial output).
8. Single assembly pass — generate() delegates to generateTracked(), which produces both the public files and the provenance the embedded layer reads; no project is assembled twice.
9. Definition validation — structure, prototype-pollution keys, and file-count / total-size caps for untrusted stores.
10. Prototype-pollution defense — deepMerge skips __proto__/constructor/prototype, with a regression test proving Object.prototype stays clean.

Follow-ups also done

• Deployment contract no longer marks PORT required (it has a default); /health is asserted because all three service frameworks generate it — verified.
• _extensions moved to a WeakMap; GeneratedProject is now exactly { config, files, summary, diagnostics, metadata, deploymentContract }.
• Recursive protected-field flattening with dot-safe key paths.
• PackkitValidationError.code and PackkitWriteError.{path,destination,cause}.

12 new tests (84 total, all green). Embedded integration covers ts-lib/cli/react-app/node-service — each generated through the API, written, then installed/built/tested/linted, with the service confirmed responding on /health. CLI, web configurator, and MCP behavior unchanged.

[DanMat]

Fixed the mode-preservation issue — good catch, that would have quietly eroded the drift signal.

createProjectFromDefinition now threads the stored modes through extendProject (internal fileModes) instead of re-deriving them against the current base, so an original add stays add across repeated export/import cycles. Verified through a double round-trip: the mode is still add after two replays. Both regression tests you specified (add and replace) are in.

Also folded in the byte-counting fix — definition size now uses Buffer.byteLength(content, 'utf8') so the limit and the diagnostic agree for multibyte content.

The two remaining follow-ups are non-blocking and I've added them to the roadmap so they don't get lost:

• Writer threat model — document that it's safe against hostile file maps and pre-existing symlinks but not race-proof against a concurrent process mutating the destination (a TOCTOU window between preflight and write). Intended use is a private temp workspace.
• driftPolicy: 'report' | 'error' — make throwing on a replay collision opt-in, and until then document that a returned project may carry error-severity diagnostics without createProjectFromDefinition having thrown.

85 tests pass, CI green.