@bernierllc/package-manager

A comprehensive package lifecycle management service for monorepo packages. This service coordinates package creation, updates, validation, and management operations using core packages for analysis and validation.

Features

• Package Lifecycle Management: Create, update, delete, and validate packages
• Dependency Management: Update, check, and install dependencies
• Package Validation: Comprehensive validation with auto-fix capabilities
• Metadata Operations: Get, set, and validate package.json fields
• Backup and Restore: Automatic backup and restore functionality
• Publishing Support: Publish and unpublish packages
• Migration Support: Package migration between versions
• Real Filesystem Operations: No mocks - uses actual filesystem operations

Installation

npm install @bernierllc/package-manager

Usage

Basic Usage

import { PackageManager } from '@bernierllc/package-manager';

const packageManager = new PackageManager({
  workspacePath: '/path/to/workspace',
  packageManager: 'npm',
  validationEnabled: true,
  autoFix: true
});

// Create a new package
const result = await packageManager.createPackage({
  name: 'my-package',
  description: 'A new package',
  version: '1.0.0',
  private: true
});

// Update package
const updateResult = await packageManager.updatePackage('/path/to/package', {
  version: '2.0.0',
  description: 'Updated description'
});

// Validate package
const validation = await packageManager.validatePackage('/path/to/package');

Package Creation

const options = {
  name: 'my-package',
  description: 'A new package',
  version: '1.0.0',
  author: 'John Doe',
  license: 'MIT',
  private: false,
  keywords: ['typescript', 'utility'],
  dependencies: {
    'lodash': '^4.17.21'
  },
  devDependencies: {
    'typescript': '^5.0.0'
  },
  scripts: {
    build: 'tsc',
    test: 'jest'
  },
  directory: '/custom/path' // Optional custom directory
};

const result = await packageManager.createPackage(options);

Package Updates

// Update version
await packageManager.updatePackage('/path/to/package', {
  version: '2.0.0'
});

// Update with version bump
await packageManager.updatePackage('/path/to/package', {
  bumpVersion: 'minor' // major, minor, patch, premajor, preminor, prepatch, prerelease
});

// Update dependencies
await packageManager.updatePackage('/path/to/package', {
  dependencies: {
    'lodash': '^4.17.21'
  },
  devDependencies: {
    'typescript': '^5.0.0'
  }
});

// Update custom fields
await packageManager.updatePackage('/path/to/package', {
  fields: {
    homepage: 'https://example.com',
    repository: {
      type: 'git',
      url: 'https://github.com/user/repo'
    }
  }
});

Dependency Management

// Update specific dependencies
await packageManager.updateDependencies('/path/to/package', {
  dependencies: ['lodash', 'axios'],
  version: '^4.17.21',
  type: 'dependencies' // dependencies, devDependencies, peerDependencies, optionalDependencies
});

// Get all dependencies
const dependencies = await packageManager.getDependencies('/path/to/package');

// Check dependencies for updates and vulnerabilities
const dependencyInfo = await packageManager.checkDependencies('/path/to/package');

// Install dependencies
await packageManager.installDependencies('/path/to/package');

Package Validation

// Validate package
const validation = await packageManager.validatePackage('/path/to/package');

if (!validation.isValid) {
  console.log('Validation errors:', validation.errors);
  console.log('Validation warnings:', validation.warnings);
  console.log('Validation score:', validation.score);
}

// Auto-fix package issues
const fixResult = await packageManager.fixPackage('/path/to/package');

Package Metadata Operations

// Get package metadata
const metadata = await packageManager.getPackageMetadata('/path/to/package');

// Get specific field
const version = await packageManager.getPackageField('/path/to/package', 'version');

// Set specific field
await packageManager.setPackageField('/path/to/package', 'homepage', 'https://example.com');

Publishing

// Publish package
const publishResult = await packageManager.publishPackage('/path/to/package');

// Unpublish package
await packageManager.unpublishPackage('package-name', '1.0.0'); // version is optional

Backup and Restore

// Create backup
const backupPath = await packageManager.backupPackage('/path/to/package');

// Restore from backup
await packageManager.restorePackage('/path/to/package', backupPath);

Configuration

const config = {
  workspacePath: process.cwd(), // Workspace root directory
  packageManager: 'npm', // npm, yarn, pnpm
  validationEnabled: true, // Enable package validation
  autoFix: false, // Auto-fix validation issues
  backupEnabled: true, // Enable automatic backups
  dryRun: false, // Dry run mode (no actual changes)
  verbose: false, // Verbose logging
  timeoutMs: 300000 // 5 minutes timeout
};

const packageManager = new PackageManager(config);

API Reference

PackageManager

Constructor

new PackageManager(config?: PackageManagerConfig)

Methods

• createPackage(options: PackageCreationOptions): Promise<PackageOperationResult>
• updatePackage(packagePath: string, options: PackageUpdateOptions): Promise<PackageOperationResult>
• deletePackage(packagePath: string): Promise<PackageOperationResult>
• validatePackage(packagePath: string): Promise<PackageValidationResult>
• fixPackage(packagePath: string): Promise<PackageOperationResult>
• getPackageMetadata(packagePath: string): Promise<PackageMetadata>
• setPackageField(packagePath: string, field: string, value: any): Promise<PackageOperationResult>
• getPackageField(packagePath: string, field: string): Promise<any>
• updateDependencies(packagePath: string, options: DependencyUpdateOptions): Promise<PackageOperationResult>
• getDependencies(packagePath: string): Promise<DependencyInfo[]>
• checkDependencies(packagePath: string): Promise<DependencyInfo[]>
• installDependencies(packagePath: string): Promise<PackageOperationResult>
• publishPackage(packagePath: string): Promise<PackageOperationResult>
• unpublishPackage(packageName: string, version?: string): Promise<PackageOperationResult>
• backupPackage(packagePath: string): Promise<string>
• restorePackage(packagePath: string, backupPath: string): Promise<PackageOperationResult>
• generatePackageJson(template: string, options: PackageCreationOptions): Promise<PackageMetadata>
• validatePackageJson(packageJson: PackageMetadata): Promise<PackageValidationResult>
• migratePackage(packagePath: string, targetVersion: string): Promise<PackageMigrationResult>

Types

PackageOperationResult

interface PackageOperationResult {
  success: boolean;
  operation: PackageOperation;
  packageName: string;
  packagePath: string;
  changes: PackageChange[];
  errors: Error[];
  warnings: string[];
  duration: number;
  timestamp: Date;
}

PackageValidationResult

interface PackageValidationResult {
  isValid: boolean;
  packageName: string;
  packagePath: string;
  errors: PackageValidationError[];
  warnings: PackageValidationWarning[];
  suggestions: string[];
  score: number; // 0-100
}

PackageMetadata

interface PackageMetadata {
  name: string;
  version: string;
  description?: string;
  keywords?: string[];
  author?: string | { name: string; email?: string; url?: string };
  license?: string;
  repository?: { type: string; url: string; directory?: string };
  homepage?: string;
  bugs?: { url: string; email?: string };
  main?: string;
  module?: string;
  types?: string;
  exports?: any;
  files?: string[];
  scripts?: Record<string, string>;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  optionalDependencies?: Record<string, string>;
  bundledDependencies?: string[];
  engines?: Record<string, string>;
  private?: boolean;
  publishConfig?: Record<string, any>;
  [key: string]: any;
}

Error Handling

The package manager provides comprehensive error handling:

try {
  const result = await packageManager.createPackage(options);
  
  if (!result.success) {
    console.error('Operation failed:', result.errors);
    console.warn('Warnings:', result.warnings);
  } else {
    console.log('Changes made:', result.changes);
  }
} catch (error) {
  console.error('Unexpected error:', error);
}

Testing

npm test
npm run test:watch
npm run test:coverage

Integration with Core Packages

This service integrates with the following core packages:

• @bernierllc/package-analyzer: For package analysis and status checking
• @bernierllc/package-validator: For package validation and structure checking

License

This package is licensed under the same terms as the parent project.