Skip to content

development.md

Latest commit

 

History

History
92 lines (72 loc) · 5.32 KB

development.md

File metadata and controls

92 lines (72 loc) · 5.32 KB
Raw

Development

Emulsify CLI is a TypeScript project that builds to the dist directory and publishes the emulsify binary from dist/index.js.

Setup

Use the Node.js version in .nvmrc, which should satisfy the package requirement of Node.js 24 or newer.

nvm use
npm install
npm run build
npm link

After npm link, run the local CLI:

emulsify --help

Source Layout

Path Purpose
src/index.ts Commander command composition and top-level error handling.
src/handlers Command handlers for init, system, and component commands.
src/handlers/hofs Shared handler wrappers, including progress and system-loading helpers.
src/lib Logging, constants, and CLI error primitives.
src/schemas JSON Schemas for project, system, and variant configuration.
src/scripts TypeScript maintenance scripts, including schema type generation.
src/types Type modules. Generated schema types are prefixed with _.
src/util Platform detection, cache utilities, filesystem helpers, component generation, and project config utilities.
scripts Package verification and release-calculation scripts, plus their regression tests.

Scripts

Script Purpose
npm run clean Remove all generated files from dist.
npm run build Clean dist, generate schema types, compile the runtime package, and mark the CLI bin executable.
npm run build-schema-types Generate TypeScript definitions from JSON Schema files.
npm run build-ts Compile TypeScript with tsconfig.dist.json.
npm run pack:dry-run Inspect npm's structured package manifest and assert the expected runtime-only contents.
npm run smoke:pack Pack the real tarball, install it in a clean temporary project, and run the installed CLI.
npm run watch Rebuild when files in src change.
npm run watch-ts Recompile TypeScript when files in src change.
npm run format Run Prettier on source TypeScript and JavaScript files.
npm run lint Run the complete test suite through npm run test.
npm run test Run Jest coverage and release-automation regression tests.
npm run test:unit Run the Jest unit suite with coverage.
npm run test:release Run the release-calculation integration tests with Node's test runner.
npm run type Run TypeScript checking without emitting files.
npm run twatch Run Jest without coverage in watch mode.
npm run version:develop Update package metadata from the complete unreleased conventional-commit history.
npm run release:analyze Verify the predicted release without invoking publishing plugins.
npm run release:verify Run every build, test, package, smoke, and release-analysis gate used before publication.
npm run semantic-release Publish through semantic-release; use -- --dry-run unless publication is explicitly intended.

Run one test file by passing the path after --:

npm run test:unit -- src/handlers/componentCreate.test.ts

Generated Types

Schema-derived type files live in src/types and are generated by:

npm run build-schema-types

Run this after changing files in src/schemas.

Local Verification

Before opening a PR, run:

npm ci
npm run build
npm run type
npm run test
npm run pack:dry-run
npm run smoke:pack

The package checks verify npm's actual file list, create the real tarball, install it with its declared runtime dependencies, and exercise emulsify --help and emulsify --version. Temporary tarballs and install projects are removed whether the smoke test passes or fails.