@turtlepusher/deployment

Release management, CI/CD, and versioning module for Cognition v3.

Features

• Version Bumping: Automatic version management (major, minor, patch, prerelease)
• Changelog Generation: Generate changelogs from conventional commits
• Git Integration: Automatic tagging and committing
• NPM Publishing: Publish packages with tag support (alpha, beta, latest)
• Pre-Release Validation: Lint, test, build, and dependency checks
• Dry Run Mode: Test releases without making changes

Installation

npm install @turtlepusher/deployment

Quick Start

Prepare a Release

import { prepareRelease } from '@turtlepusher/deployment';

// Bump patch version and generate changelog
const result = await prepareRelease({
  bumpType: 'patch',
  generateChangelog: true,
  createTag: true,
  commit: true
});

console.log(`Released ${result.newVersion}`);

Publish to NPM

import { publishToNpm } from '@turtlepusher/deployment';

// Publish with 'latest' tag
const result = await publishToNpm({
  tag: 'latest',
  access: 'public'
});

console.log(`Published ${result.packageName}@${result.version}`);

Validate Package

import { validate } from '@turtlepusher/deployment';

// Run all validation checks
const result = await validate({
  lint: true,
  test: true,
  build: true,
  checkDependencies: true
});

if (!result.valid) {
  console.error('Validation failed:', result.errors);
}

API Reference

ReleaseManager

import { ReleaseManager } from '@turtlepusher/deployment';

const manager = new ReleaseManager();

// Prepare release with options
const result = await manager.prepareRelease({
  bumpType: 'minor',           // major | minor | patch | prerelease
  version: '2.0.0',            // Override version
  channel: 'beta',             // alpha | beta | rc | latest
  generateChangelog: true,     // Generate CHANGELOG.md
  createTag: true,             // Create git tag
  commit: true,                // Commit changes
  dryRun: false,               // Test without changes
  skipValidation: false,       // Skip validation checks
  tagPrefix: 'v',              // Tag prefix (v2.0.0)
  changelogPath: 'CHANGELOG.md' // Changelog file path
});

Version Bumping

// Bump patch: 1.0.0 -> 1.0.1
await manager.prepareRelease({ bumpType: 'patch' });

// Bump minor: 1.0.0 -> 1.1.0
await manager.prepareRelease({ bumpType: 'minor' });

// Bump major: 1.0.0 -> 2.0.0
await manager.prepareRelease({ bumpType: 'major' });

// Bump prerelease: 1.0.0 -> 1.0.0-alpha.1
await manager.prepareRelease({ bumpType: 'prerelease', channel: 'alpha' });

// Increment prerelease: 1.0.0-alpha.1 -> 1.0.0-alpha.2
await manager.prepareRelease({ bumpType: 'prerelease', channel: 'alpha' });

Changelog Generation

Generates changelog from conventional commits:

# Commit format: type(scope): message
git commit -m "feat(api): add new endpoint"
git commit -m "fix(auth): resolve login issue"
git commit -m "feat(ui): update design BREAKING CHANGE: new layout"

Generated changelog:

## [2.0.0] - 2026-01-04

### BREAKING CHANGES

- **ui**: update design BREAKING CHANGE: new layout

### Features

- **api**: add new endpoint
- **ui**: update design

### Bug Fixes

- **auth**: resolve login issue

Publisher

import { Publisher } from '@turtlepusher/deployment';

const publisher = new Publisher();

// Publish to npm
const result = await publisher.publishToNpm({
  tag: 'latest',              // npm tag (alpha, beta, latest)
  access: 'public',           // public | restricted
  dryRun: false,              // Test publish without actual publish
  registry: 'https://registry.npmjs.org/',
  otp: '123456',              // 2FA OTP code
  skipBuild: false,           // Skip build step
  buildCommand: 'npm run build' // Custom build command
});

// Check if version exists
const exists = await publisher.checkVersionExists('my-package', '1.0.0');

// Get latest version
const latest = await publisher.getLatestVersion('my-package', 'latest');

// Verify npm authentication
const authenticated = await publisher.verifyAuth();

// Pack to tarball
const tarball = await publisher.pack('./dist');

Validator

import { Validator } from '@turtlepusher/deployment';

const validator = new Validator();

// Validate package
const result = await validator.validate({
  lint: true,                 // Run linter
  test: true,                 // Run tests
  build: true,                // Run build
  checkDependencies: true,    // Check dependencies
  checkGitStatus: true,       // Check uncommitted changes
  lintCommand: 'npm run lint',
  testCommand: 'npm test',
  buildCommand: 'npm run build'
});

console.log('Valid:', result.valid);
console.log('Errors:', result.errors);
console.log('Warnings:', result.warnings);
console.log('Checks:', result.checks);

Complete Release Workflow

import { Validator, ReleaseManager, Publisher } from '@turtlepusher/deployment';

async function release(version: string, tag: string) {
  // 1. Validate package
  console.log('Validating package...');
  const validator = new Validator();
  const validation = await validator.validate();

  if (!validation.valid) {
    console.error('Validation failed:', validation.errors);
    process.exit(1);
  }

  // 2. Prepare release
  console.log('Preparing release...');
  const manager = new ReleaseManager();
  const release = await manager.prepareRelease({
    version,
    generateChangelog: true,
    createTag: true,
    commit: true
  });

  if (!release.success) {
    console.error('Release preparation failed:', release.error);
    process.exit(1);
  }

  // 3. Publish to npm
  console.log('Publishing to npm...');
  const publisher = new Publisher();
  const publish = await publisher.publishToNpm({
    tag,
    access: 'public'
  });

  if (!publish.success) {
    console.error('Publish failed:', publish.error);
    process.exit(1);
  }

  console.log(`Successfully released ${publish.packageName}@${publish.version}`);
}

// Run release
release('2.0.0', 'latest');

CLI Usage

# Prepare release
npx @turtlepusher/deployment release --version 2.0.0 --changelog --tag

# Publish to npm
npx @turtlepusher/deployment publish --tag latest --access public

# Validate package
npx @turtlepusher/deployment validate

Dry Run Mode

Test releases without making changes:

// Test release preparation
await prepareRelease({
  bumpType: 'minor',
  dryRun: true
});

// Test npm publish
await publishToNpm({
  tag: 'beta',
  dryRun: true
});

Channel/Tag Strategy

• alpha: Early development versions (1.0.0-alpha.1)
• beta: Feature complete, testing (1.0.0-beta.1)
• rc: Release candidate (1.0.0-rc.1)
• latest: Stable production release (1.0.0)

// Prerelease workflow
await prepareRelease({ bumpType: 'prerelease', channel: 'alpha' }); // 1.0.0-alpha.1
await publishToNpm({ tag: 'alpha' });

await prepareRelease({ bumpType: 'prerelease', channel: 'beta' });  // 1.0.0-beta.1
await publishToNpm({ tag: 'beta' });

await prepareRelease({ bumpType: 'patch' });  // 1.0.0
await publishToNpm({ tag: 'latest' });

Environment Variables

# NPM authentication
export NPM_TOKEN="your-token"

# Custom registry
export NPM_CONFIG_REGISTRY="https://registry.npmjs.org/"

Error Handling

try {
  const result = await prepareRelease({ bumpType: 'minor' });

  if (!result.success) {
    console.error('Release failed:', result.error);
    console.warn('Warnings:', result.warnings);
  }
} catch (error) {
  console.error('Unexpected error:', error);
}

License

MIT