Architecture

Overview

Universal Release Tool is a plugin-based release automation system supporting multiple package ecosystems through a unified interface.

Core Concepts

1. Adapters

Each ecosystem (npm, Cargo, Docker, etc.) has an adapter implementing the PackageManagerAdapter interface:

interface PackageManagerAdapter {
  // Detection
  canHandle(packagePath: string): Promise<boolean>;

  // Version management
  readVersion(packagePath: string): Promise<string>;
  writeVersion(packagePath: string, version: string): Promise<void>;

  // Metadata
  getPackageInfo(packagePath: string): Promise<PackageInfo>;

  // Validation
  validate(
    packagePath: string,
    config: EcosystemConfig,
  ): Promise<ValidationResult>;

  // Publishing
  publish(packagePath: string, config: PublishConfig): Promise<PublishResult>;
  verify(packageName: string, version: string): Promise<boolean>;

  // Rollback
  rollback(
    packageName: string,
    version: string,
    strategy: RollbackStrategy,
  ): Promise<void>;
}

2. Configuration

Single .release.yaml file with:

• Global settings (SBOM, attestation, signing)
• Ecosystem-specific configs
• Validation rules
• Registry configurations

3. Orchestrator

The ReleaseOrchestrator coordinates the release process:

1. Load configuration
2. Detect or select ecosystem
3. Run validation pipeline
4. Execute dry-run (optional)
5. Publish to registries
6. Generate SBOM
7. Create attestation
8. Sign artifacts
9. Verify publication

4. Version Manager

Uses Bun's built-in semver API for:

• Version parsing and comparison
• Bumping (major, minor, patch, prerelease)
• Conventional commits analysis
• Next version detection

Data Flow

User Command
    ↓
CLI (Commander.js)
    ↓
ReleaseOrchestrator
    ↓
    ├─→ ConfigManager (load .release.yaml)
    ├─→ AdapterRegistry (detect ecosystem)
    ├─→ VersionManager (version operations)
    └─→ PackageManagerAdapter
        ├─→ Validate
        ├─→ Dry-run
        ├─→ Publish
        └─→ Verify

Ecosystem Adapters

npm/pnpm/yarn

• Detects: package.json
• Publishes via: npm publish, pnpm publish, yarn publish
• Rollback: npm deprecate

Cargo (Rust)

• Detects: Cargo.toml
• Publishes via: cargo publish
• Rollback: cargo yank

Docker/OCI

• Detects: Dockerfile
• Publishes via: docker push
• Supports: Multiple registries (GHCR, Docker Hub, etc.)

Python/PyPI

• Detects: setup.py or pyproject.toml
• Publishes via: twine upload
• Rollback: Not supported (PyPI policy)

Go Modules

• Detects: go.mod
• Publishes via: Git tags + proxy notification
• Registry: pkg.go.dev

Security Features

SBOM Generation

• Uses external tools (syft, cyclonedx-cli)
• Supports SPDX and CycloneDX formats
• Generated pre-publish

Provenance Attestation

• SLSA framework support
• In-toto integration
• Attaches to published artifacts

Artifact Signing

• Cosign for container images
• GPG for traditional packages
• Key management via environment variables

Extension Points

Adding New Ecosystems

1. Create adapter in src/adapters/
2. Implement PackageManagerAdapter
3. Register in CLI
4. Add config schema
5. Document in README

Custom Validation

Adapters can override:

• validate(): Custom validation logic
• build(): Build steps
• test(): Test execution

Pre/Post Hooks

Configure via prePublishScripts:

ecosystems:
  npm:
    prePublishScripts:
      - npm audit
      - npm run security-check

Performance

• Bun runtime for fast startup
• Lazy adapter loading
• Parallel validation where possible
• Caching of git operations

Error Handling

• Structured error types
• Rollback on failure (when supported)
• Detailed error messages with context
• Exit codes for CI/CD integration

Testing Strategy

• Unit tests for version management
• Integration tests for adapters
• Mock registries for publish tests
• GitHub Actions CI/CD

Future Enhancements

• Plugin system for custom adapters
• Monorepo support (Nx, Turborepo)
• Changelog generation
• GitLab CI integration
• Web UI for configuration
• Analytics and telemetry