tessl/npm-release-it

Generic CLI tool to automate versioning and package publishing-related tasks.

—

Pending

Overview

Eval results

Files

Core Release Orchestration

Name: tessl/npm-release-it
Author: tessl

The core orchestration system manages the complete release workflow, coordinating plugins, managing lifecycle hooks, and maintaining shared context across all release operations.

Capabilities

Main Release Function

The primary function for executing release workflows with full plugin coordination.

/**
 * Execute complete release workflow with plugin orchestration
 * @param options - Release configuration options including increment, mode flags, and plugin settings
 * @param dependencies - Optional dependency injection container for testing and customization
 * @returns Promise resolving to release results including version information and changelog
 */
function runTasks(
  options: ReleaseOptions,
  dependencies?: DependencyContainer
): Promise<ReleaseResult>;

interface ReleaseOptions {
  /** Version increment: 'major', 'minor', 'patch', 'prerelease', or explicit version */
  increment?: string | boolean;
  /** Dry run mode - show operations without executing */
  "dry-run"?: boolean;
  /** Verbose output level (boolean or number 1-2) */
  verbose?: boolean | number;
  /** CI mode - non-interactive operation */
  ci?: boolean;
  /** Prompt only for version selection */
  "only-version"?: boolean;
  /** Print release version and exit */
  "release-version"?: boolean;
  /** Print changelog and exit */
  changelog?: boolean;
  /** Configuration file path or false to disable */
  config?: string | boolean;
  /** Configuration directory */
  configDir?: string;
  /** Extend configuration */
  extends?: string | false;
  /** Plugin-specific options */
  git?: GitOptions;
  npm?: NpmOptions;
  github?: GitHubOptions;
  gitlab?: GitLabOptions;
  hooks?: HooksOptions;
  [key: string]: any;
}

interface ReleaseResult {
  /** Package or project name */
  name: string;
  /** Generated changelog content */
  changelog: string;
  /** Previous version before release */
  latestVersion: string;
  /** New version after release */
  version: string;
}

interface DependencyContainer {
  /** Configuration instance */
  config?: Config;
  /** Logger instance */
  log?: Logger;
  /** Shell execution instance */
  shell?: Shell;
  /** Progress spinner instance */
  spinner?: Spinner;
  /** Interactive prompt instance */
  prompt?: Prompt;
}

Hook System

Execute custom commands at specific points in the release workflow.

interface HooksOptions {
  /** Commands to run before any operation */
  "before:init"?: string | string[];
  /** Commands to run after initialization */
  "after:init"?: string | string[];
  /** Commands to run before version bump */
  "before:bump"?: string | string[];
  /** Commands to run after version bump */
  "after:bump"?: string | string[];
  /** Commands to run before release */
  "before:release"?: string | string[];
  /** Commands to run after release */
  "after:release"?: string | string[];
  /** Commands to run before git operations */
  "before:git:init"?: string | string[];
  "before:git:bump"?: string | string[];
  "before:git:release"?: string | string[];
  /** Commands to run after git operations */
  "after:git:init"?: string | string[];
  "after:git:bump"?: string | string[];
  "after:git:release"?: string | string[];
  /** Commands to run before npm operations */
  "before:npm:init"?: string | string[];
  "before:npm:bump"?: string | string[];
  "before:npm:release"?: string | string[];
  /** Commands to run after npm operations */
  "after:npm:init"?: string | string[];
  "after:npm:bump"?: string | string[];
  "after:npm:release"?: string | string[];
  /** Commands to run before GitHub operations */
  "before:github:init"?: string | string[];
  "before:github:release"?: string | string[];
  /** Commands to run after GitHub operations */
  "after:github:init"?: string | string[];
  "after:github:release"?: string | string[];
}

Usage Examples:

import runTasks from "release-it";

// Basic programmatic release
const result = await runTasks({
  increment: "minor",
  "dry-run": false,
  ci: true
});

console.log(`Released ${result.name} v${result.version}`);

// Release with custom hooks
const result = await runTasks({
  increment: "patch",
  hooks: {
    "before:bump": "npm test",
    "after:release": ["npm run build", "npm run deploy"]
  }
});

// Release with dependency injection for testing
const mockContainer = {
  shell: mockShell,
  log: mockLogger
};

const result = await runTasks(
  { increment: "patch", "dry-run": true },
  mockContainer
);

Version Increment Options

Release It! supports semantic versioning increments and custom version specification.

type VersionIncrement = 
  | "major"        // 1.0.0 -> 2.0.0
  | "minor"        // 1.0.0 -> 1.1.0  
  | "patch"        // 1.0.0 -> 1.0.1
  | "prerelease"   // 1.0.0 -> 1.0.1-0
  | "premajor"     // 1.0.0 -> 2.0.0-0
  | "preminor"     // 1.0.0 -> 1.1.0-0
  | "prepatch"     // 1.0.0 -> 1.0.1-0
  | string         // Explicit version like "2.1.0"
  | false;         // No version increment

Context System

Shared context system for template variables and plugin communication.

interface ReleaseContext {
  /** Package or project name */
  name?: string;
  /** Current version */
  version?: string;
  /** Previous version */
  latestVersion?: string;
  /** Generated changelog */
  changelog?: string;
  /** Git tag name */
  tagName?: string;
  /** Repository URL */
  repo?: {
    remote?: string;
    protocol?: string;
    host?: string;
    owner?: string;
    repository?: string;
    project?: string;
  };
  /** npm package information */
  npm?: {
    name?: string;
    tag?: string;
    registry?: string;
  };
  /** GitHub release information */
  github?: {
    releaseUrl?: string;
    releaseId?: number;
  };
}

Templates in configuration files and hooks can use context variables:

{
  "git": {
    "commitMessage": "Release ${version}",
    "tagAnnotation": "Release ${version}\n\n${changelog}"
  },
  "hooks": {
    "after:release": "echo Released ${name} v${version}"
  }
}

Install with Tessl CLI