@bernierllc/workspace-manager

Pure workspace management utilities for monorepo package discovery and configuration.

Features

• Workspace Detection: Automatically detect npm, yarn, pnpm, and lerna workspaces
• Package Discovery: Find all packages in a workspace with proper path resolution
• Package Categorization: Organize packages by type (core, service, suite, ui, util, legacy)
• Workspace Validation: Validate workspace structure and configuration
• Changeset Integration: Resolve package paths correctly for changeset CLI

Installation

npm install @bernierllc/workspace-manager

Usage

Basic Workspace Detection

import { detectWorkspaceType, getWorkspaceConfig } from '@bernierllc/workspace-manager';

// Detect workspace type
const detection = detectWorkspaceType();
console.log(detection.type); // 'npm', 'yarn', 'pnpm', 'lerna', or 'unknown'

// Get full workspace configuration
const config = getWorkspaceConfig();
console.log(config.isValid); // true/false
console.log(config.packages); // Array of package paths

Package Discovery

import { getWorkspacePackages, getCategorizedPackages } from '@bernierllc/workspace-manager';

// Get all packages with detailed information
const packages = getWorkspacePackages();
packages.forEach(pkg => {
  console.log(`${pkg.name}: ${pkg.relativePath}`);
  console.log(`  Has package.json: ${pkg.hasPackageJson}`);
  console.log(`  Is directory: ${pkg.isDirectory}`);
});

// Get packages organized by category
const categorized = getCategorizedPackages();
categorized.forEach(pkg => {
  console.log(`${pkg.name} (${pkg.category}): ${pkg.relativePath}`);
});

Workspace Validation

import { validateWorkspaceStructure } from '@bernierllc/workspace-manager';

// Validate workspace structure
const result = validateWorkspaceStructure();

if (result.isValid) {
  console.log('✅ Workspace is valid');
} else {
  console.log('❌ Workspace has issues:');
  result.errors.forEach(error => console.log(`  - ${error}`));
}

// Validate with strict options
const strictResult = validateWorkspaceStructure('.', {
  requirePackageJson: true,
  allowedCategories: ['core', 'service', 'suite']
});

Changeset Integration

import { resolvePackagePaths } from '@bernierllc/workspace-manager';

// Get package paths for changeset CLI
try {
  const paths = resolvePackagePaths();
  console.log('Package paths for changeset:', paths);
} catch (error) {
  console.error('Invalid workspace configuration:', error.message);
}

API Reference

detectWorkspaceType(rootPath?: string): WorkspaceDetectionResult

Detect the type of workspace in the given directory.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())

Returns:

• WorkspaceDetectionResult with type, confidence, and detection reason

getWorkspaceConfig(rootPath?: string): WorkspaceConfig

Get complete workspace configuration.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())

Returns:

• WorkspaceConfig with type, packages, validation status, and errors

getWorkspacePackages(rootPath?: string): PackageInfo[]

Get detailed information about all packages in the workspace.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())

Returns:

• Array of PackageInfo objects with package details

getPackageCategories(rootPath?: string): Record<PackageCategory, string[]>

Get packages organized by category.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())

Returns:

• Object mapping categories to arrays of package paths

getCategorizedPackages(rootPath?: string): CategorizedPackage[]

Get packages with category information.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())

Returns:

• Array of CategorizedPackage objects

validateWorkspaceStructure(rootPath?: string, options?: WorkspaceValidationOptions): WorkspaceValidationResult

Validate workspace structure and configuration.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())
• options (optional): Validation options

Returns:

• WorkspaceValidationResult with validation status, errors, and warnings

resolvePackagePaths(rootPath?: string): string[]

Resolve package paths for changeset CLI integration.

Parameters:

• rootPath (optional): Path to workspace root (defaults to process.cwd())

Returns:

• Array of package paths relative to workspace root

Throws:

• Error if workspace configuration is invalid

Types

WorkspaceType

type WorkspaceType = 'npm' | 'yarn' | 'pnpm' | 'lerna' | 'unknown';

PackageCategory

type PackageCategory = 'core' | 'service' | 'suite' | 'ui' | 'util' | 'legacy' | 'unknown';

WorkspaceConfig

interface WorkspaceConfig {
  type: WorkspaceType;
  packages: string[];
  rootPath: string;
  configPath?: string;
  isValid: boolean;
  errors: string[];
}

PackageInfo

interface PackageInfo {
  name: string;
  path: string;
  relativePath: string;
  packageJsonPath: string;
  hasPackageJson: boolean;
  isDirectory: boolean;
}

Supported Workspace Types

npm Workspaces

Detected by package.json with workspaces field:

{
  "workspaces": ["packages/*"]
}

Yarn Workspaces

Detected by presence of yarn.lock and package.json with workspaces field.

pnpm Workspaces

Detected by presence of pnpm-workspace.yaml:

packages:
  - 'packages/*'

Lerna Workspaces

Detected by presence of lerna.json:

{
  "packages": ["packages/*"]
}

Package Categories

Packages are automatically categorized based on their directory structure:

• core: packages/core/* - Atomic utilities and pure functions
• service: packages/service/* - Business logic and orchestration
• suite: packages/suite/* - Complete end-to-end solutions
• ui: packages/ui/* - React components and UI utilities
• util: packages/util/* - Utility packages
• legacy: Other packages or legacy structure
• unknown: Unable to determine category

Error Handling

The package provides comprehensive error handling:

try {
  const config = getWorkspaceConfig();
  if (!config.isValid) {
    console.error('Workspace configuration errors:', config.errors);
    return;
  }
  
  const packages = getWorkspacePackages();
  console.log(`Found ${packages.length} packages`);
} catch (error) {
  console.error('Failed to analyze workspace:', error.message);
}

Testing

npm test

Contributing

This package is part of the Bernier LLC tools ecosystem. Please follow the project's contribution guidelines.

License

UNLICENSED - Bernier LLC proprietary software