# Tumbi-Assembler

*Tumbi-Assembler* is a distribution compose tool adapted from Pungi for ParticleOS, an immutable Debian-based Linux distribution.

## Project Overview

Tumbi-Assembler is a fundamental adaptation of Pungi's distribution compose system to work with the Debian/APT package ecosystem. It enables the creation of ParticleOS distribution snapshots containing:

- **OSTree repositories** (using apt-ostree)
- **Container images** (using bootc-deb)
- **Live installation ISOs** (using Calamares installer)
- **Package repositories** (APT-compatible)

## Key Features

- **APT Package Management**: Complete integration with Debian's APT package system
- **OSTree Integration**: Atomic system updates using apt-ostree
- **Container Support**: OCI container image generation using bootc-deb
- **Live System Creation**: Calamares-based installer ISO generation
- **Future-Proof Design**: Robust, production-ready implementation with comprehensive error handling

## Architecture

Tumbi-Assembler maintains Pungi's phase-based architecture while adapting it for the Debian ecosystem:

- **Package Gathering**: APT-based package resolution and dependency management
- **Repository Creation**: APT-compatible repository generation
- **OSTree Composition**: apt-ostree integration for immutable system images
- **Container Generation**: bootc-deb integration for OCI container images
- **Live System Building**: Calamares installer integration with live-build

## Development Status

This project represents a complete adaptation of Pungi from RPM/DNF to APT/DEB ecosystems, with comprehensive documentation covering:

- **Technical Analysis**: Deep dive into Pungi's architecture and adaptation requirements
- **Implementation Plans**: Detailed roadmaps and technical specifications
- **Production-Ready Solutions**: Robust implementations addressing all technical challenges
- **Future-Proof Design**: Solutions designed for long-term maintainability

## Documentation

Comprehensive development documentation is available in the `tumbi-assembler-dev-docs/` directory:

- `PUNGI_ANALYSIS_FOR_PARTICLEOS.md` - Initial architectural analysis
- `IMPLEMENTATION_PLAN.md` - First implementation plan with code examples
- `CRITICAL_ANALYSIS_REVISION.md` - Critical review and technical challenges
- `INTEGRATION_DETAILS.md` - Detailed integration specifications
- `PRACTICAL_ROADMAP.md` - 26-week implementation timeline
- `FINAL_FUTURE_PROOF_IMPLEMENTATION.md` - Production-ready implementation

## Key Technical Achievements

- **Accurate Debian Version Parsing**: Proper handling of complex Debian version constraints
- **Complete APT Environment Management**: Self-contained build environment setup
- **Atomic Configuration Updates**: Race-condition-free system configuration
- **Future-Proof Group Resolution**: Multiple data sources with consistent logic
- **Zero External Dependencies**: Pure Python implementations using python-apt

## ParticleOS Integration

Tumbi-Assembler is specifically designed for ParticleOS, providing:

- **Immutable System Support**: OSTree-based atomic updates
- **Container Deployment**: bootc-deb integration for container-based deployment
- **Modern Installer**: Calamares-based installation experience
- **Debian Compatibility**: Full compatibility with Debian package ecosystem

## Links

- **Original Pungi**: https://pagure.io/pungi/
- **ParticleOS**: [ParticleOS Project]
- **Development Documentation**: See `tumbi-assembler-dev-docs/` directory

## License

This project is based on Pungi and maintains compatibility with its licensing terms.