# Debian Forge File Structure Reorganization Plan
# Goal: Achieve near 1:1 compatibility with original osbuild repository structure

## Phase 1: Restore Original Structure
- [x] Verify core directories exist and are complete:
  - [x] .devcontainer/
  - [x] .github/
  - [x] assemblers/
  - [x] data/
  - [x] devices/
  - [x] docs/
  - [x] inputs/
  - [x] mounts/
  - [x] osbuild/          # Core Python package
  - [x] runners/
  - [x] schemas/
  - [x] schutzbot/
  - [x] selinux/
  - [x] sources/
  - [x] stages/
  - [x] test/
  - [x] tools/
  - [x] samples/

- [x] Restore missing configuration files:
  - [x] .bandit
  - [x] .editorconfig
  - [x] .git-blame-ignore-revs
  - [x] .gitignore
  - [x] .gitlab-ci.yml
  - [x] .mypy.ini
  - [x] .packit.yaml
  - [x] .ruff.toml
  - [x] CODEOWNERS
  - [x] Schutzfile
  - [x] osbuild.spec
  - [x] setup.cfg
  - [x] tox.ini

## Phase 2: Reorganize Debian-Specific Content ✅ COMPLETED
- [x] Move Debian documentation to docs/:
  - [x] debian-forge-docs/ → docs/debian/
  - [x] Keep original docs/ structure intact

- [x] Move Debian tests to test/:
  - [x] debian-forge-tests/ → test/debian/
  - [x] Ensure original test/ structure remains

- [x] Move Debian blueprints to samples/:
  - [x] blueprints/ → test/data/manifests/debian/
  - [x] Keep original samples/ content

- [x] Move Debian stages to stages/:
  - [x] Ensure Debian stages integrate with existing stage structure
  - [x] Maintain original stage organization

## Phase 3: Clean Up Root Directory ✅ COMPLETED
- [x] Move Python scripts to appropriate locations:
  - [x] composer_*.py → tools/ (if CLI tools) or osbuild/ (if core modules)
  - [x] debian_*.py → osbuild/ (core modules)
  - [x] build_*.py → osbuild/ (core modules)

- [x] Remove custom build directories:
  - [x] build-environments/ → Move to .osbuild/ or create proper build system integration
  - [x] build-logs/ → Move to .osbuild/ or create proper build system integration
  - [x] artifacts/ → Move to .osbuild/ or create proper build system integration

## Phase 4: Maintain Debian Functionality ✅ COMPLETED
- [x] Ensure Debian stages work with original pipeline system
- [x] Integrate Debian package management with existing stage architecture
- [x] Maintain OSTree support alongside original features

## Implementation Steps
1. [x] Audit current structure against original osbuild repository
2. [x] Create backup of current Debian-specific work
3. [x] Restore original structure from upstream
4. [x] Reintegrate Debian components into proper locations
5. [x] Test functionality to ensure nothing breaks
6. [x] Update documentation to reflect new structure

## Current Structure Issues Identified
- Extra directories: debian-forge-docs/, debian-forge-tests/, build-environments/, build-logs/, artifacts/ ✅ RESOLVED
- Misplaced files: Python scripts in root that should be in tools/ or osbuild/ ✅ RESOLVED
- Missing original structure: Some original directories may be incomplete ✅ VERIFIED COMPLETE
- Custom additions: Debian-specific files mixed with core structure ✅ REORGANIZED

## Priority Order
1. High: Restore core osbuild structure ✅ COMPLETED
2. Medium: Reorganize Debian content ✅ COMPLETED
3. Low: Clean up and optimize ✅ COMPLETED
4. Critical: Maintain all Debian functionality during transition ✅ COMPLETED

## Progress Summary
✅ **Phase 1**: Original structure restored and verified
✅ **Phase 2**: Debian content reorganized into proper locations
✅ **Phase 3**: Root directory cleaned up
✅ **Phase 4**: Debian functionality maintained

## Next Steps
- [x] Run tests to verify functionality
- [x] Update documentation references
- [x] Commit final reorganization
- [ ] Push changes to repository

## File Structure Achieved
The project now maintains the exact same directory structure as the original osbuild repository:
- All core directories present and complete
- All configuration files present
- Debian-specific content properly organized within standard structure
- Root directory clean and matches upstream
- Maintains 1:1 compatibility while preserving Debian functionality

## Final Status: ✅ REORGANIZATION COMPLETE
**All phases completed successfully!** The Debian Forge project now has:
- ✅ 1:1 file structure compatibility with upstream osbuild
- ✅ All Debian-specific functionality preserved and properly organized
- ✅ Clean root directory matching upstream structure
- ✅ Functional build system with Debian stages
- ✅ Proper integration of Debian modules within osbuild package
- ✅ Tested functionality with successful Debian manifest build

## Repository Status
- **Backup branch**: `backup-debian-changes` (contains all original work)
- **Main branch**: Reorganized structure with 1:1 upstream compatibility
- **Ready for**: Push to remote repository and continued development

## Phase 5: Debian Package Structure (NEW) 🆕
**Goal**: Mirror upstream osbuild RPM package structure with Debian packages

### Upstream osbuild RPM Structure (Reference):
- **osbuild** - Main package (core engine)
- **osbuild-depsolve-dnf** - DNF dependency solver
- **osbuild-luks2** - LUKS2 encryption support
- **osbuild-lvm2** - LVM2 support
- **osbuild-ostree** - OSTree support
- **osbuild-selinux** - SELinux support
- **osbuild-tools** - Helper tools and utilities
- **python3-osbuild** - Python library

### Target debian-forge Package Structure:
- [x] **debian-forge** - Main package (core engine and binary)
- [x] **debian-forge-depsolve-deb** - Debian package dependency solver (apt-based)
- [x] **debian-forge-luks2** - LUKS2 encryption support
- [x] **debian-forge-lvm2** - LVM2 support
- [x] **debian-forge-ostree** - OSTree support (critical for Debian Atomic)
- [x] **debian-forge-selinux** - SELinux support
- [x] **debian-forge-tools** - Helper tools and utilities
- [x] **python3-debian-forge** - Python library

### Implementation Status:
- [x] **CI/CD Workflow Created** - Comprehensive Forgejo workflow in `.forgejo/workflows/ci.yml`
- [x] **Package Definitions** - All 8 packages defined in debian/control
- [x] **Build Rules** - debian/rules with proper file distribution across packages
- [x] **Dependencies Mapped** - Proper stage-to-package distribution
- [ ] **Test Package Building** - Verify all packages build correctly
- [ ] **Test Package Installation** - Verify packages install and work
- [ ] **Push to Repository** - Get workflow running in Forgejo

### Package Dependencies:
- **debian-forge** → depends on python3-debian-forge + debian-forge-tools
- **python3-debian-forge** → core Python library with minimal deps
- **debian-forge-depsolve-deb** → depends on python3-debian-forge + libapt-pkg-dev
- **debian-forge-ostree** → depends on python3-debian-forge + ostree
- **debian-forge-luks2** → depends on python3-debian-forge + cryptsetup
- **debian-forge-lvm2** → depends on python3-debian-forge + lvm2
- **debian-forge-selinux** → depends on python3-debian-forge + selinux-policy-default
- **debian-forge-apparmor** → depends on python3-debian-forge + apparmor-policy-default (discuss if feasible)
- **debian-forge-tools** → depends on python3-debian-forge

### Stage Distribution:
- **Core stages** → python3-debian-forge
- **apt.* stages** → debian-forge-depsolve-deb
- **ostree.* stages** → debian-forge-ostree
- **luks2.* stages** → debian-forge-luks2
- **lvm2.* stages** → debian-forge-lvm2
- **selinux.* stages** → debian-forge-selinux
- **apparmor.* stages** → debian-forge-apparmor
- **tools/** → debian-forge-tools
- **Main binary** → debian-forge

### Benefits of This Structure:
- **Modular Installation** - Users can install only what they need
- **Upstream Compatibility** - Mirrors osbuild package structure exactly
- **Debian Optimization** - apt-based dependency solving instead of dnf
- **Atomic Support** - OSTree package available for Debian Atomic systems
- **Clean Dependencies** - Each package has minimal, focused dependencies

### Issues Discovered & Fixes Needed:
- [ ] **Binary Path Issue**: The workflow assumes `osbuild` is a standalone binary, but it's actually a Python package
  - **Current**: `cp osbuild debian/debian-forge/usr/bin/debian-forge`
  - **Fix**: Use Python entry point: `osbuild = osbuild.main_cli:osbuild_cli`
  - **Solution**: The `debian-forge` package should install the Python entry point, not copy a binary
  - **Update**: Modify debian/rules to use `dh_python3` properly for console scripts

### Next Actions:
1. **Fix debian/rules** - Update to handle Python entry points correctly
2. **Test local build** - Verify packages can be built locally
3. **Trigger CI** - Push fixes and let Forgejo CI run the workflow
4. **Verify packages** - Test that all 8 packages install and work correctly