Skip to content

deployment

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

deployment

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
examples
examples
 
 
src
src
 
 
QUICK_START.md
QUICK_START.md
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tmp.json
tmp.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

@claude-flow/deployment

npm version npm downloads License: MIT TypeScript CI/CD Semantic Release

Release management, CI/CD, and versioning module for Claude Flow 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 @claude-flow/deployment

Quick Start

Prepare a Release

import { prepareRelease } from '@claude-flow/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 '@claude-flow/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 '@claude-flow/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 '@claude-flow/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 '@claude-flow/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 '@claude-flow/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 '@claude-flow/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 @claude-flow/deployment release --version 2.0.0 --changelog --tag

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

# Validate package
npx @claude-flow/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