zosbuilder/docs/PROMPT.md

# **Prompt for Building Custom Alpine Initramfs with zinit**

## **Project Overview**
Build a complete system for creating a custom initramfs based on Alpine Linux 3.22 x86_64, with zinit replacing OpenRC for process management. The initramfs will be embedded into a custom kernel and must be buildable in GitHub Actions using rootless containers (Docker/Podman).

## **Technical Requirements**

### **Base System**
- **Alpine Version**: 3.22 x86_64 miniroot as base
- **Process Manager**: zinit (complete OpenRC replacement - do not install OpenRC packages)
- **Container Runtime**: Rootless Docker/Podman compatible
- **Build Tools**: Include Go, Rust, standard build tools in builder container
- **Target**: Final vmlinuz.efi with embedded initramfs.cpio.xz

### **Directory Structure to Create**
```
project-root/
├── config/
│   ├── zinit/
│   │   ├── services/          # zinit service definitions
│   │   └── zinit.conf         # main zinit configuration
│   ├── packages.list          # apk packages to install in initramfs
│   ├── sources.conf           # components to download/build (format below)
│   ├── kernel.config          # kernel config with initramfs path
│   └── modules.conf           # 2-stage module loading specification
├── scripts/
│   ├── lib/
│   │   ├── docker.sh          # container lifecycle, rootless setup
│   │   ├── alpine.sh          # miniroot extraction, apk operations
│   │   ├── components.sh      # download/build from sources.conf
│   │   ├── initramfs.sh       # assembly, aggressive cleanup, compression
│   │   ├── kernel.sh          # kernel build with embedded initramfs
│   │   └── testing.sh         # qemu/cloud-hypervisor test commands
│   ├── build.sh               # main orchestrator script
│   └── clean.sh               # cleanup all generated artifacts
├── initramfs/                 # final initramfs tree (generated)
├── components/                # component build staging (generated)
├── kernel/                    # kernel source tree (generated)
└── dist/                      # final build artifacts (generated)
```

### **Configuration File Formats**

#### **sources.conf Format**
```bash
# TYPE:NAME:URL:VERSION:BUILD_FUNCTION
git:zinit:https://github.com/zdharma-continuum/zinit:main:build_zinit
release:tool:https://github.com/user/tool/releases/download/v1.0/tool-x86_64.tar.gz:v1.0:install_tool
```

#### **packages.list Format**
```
# One APK package per line, comments with #
busybox
musl
alpine-baselayout
# NO openrc packages
```

#### **modules.conf Format**
```bash
# STAGE:MODULE_NAME:FIRMWARE_FILES (optional)
stage1:e1000e:intel/e1000e-*.bin
stage1:ahci:
stage2:iwlwifi:intel/iwlwifi-*.ucode
```

### **Build Process Specifications**

#### **Container Requirements**
- Alpine Linux base with build tools (gcc, musl-dev, go, rust, make, etc.)
- Rootless compatible: use `--user $(id -u):$(id -g)`
- Podman and Docker compatible
- Document subuid/subgid requirements in README
- Option to commit builder container for reuse

#### **Initramfs Assembly Process**
1. Extract Alpine 3.22 miniroot to `initramfs/`
2. Install packages from `packages.list` using apk (NO OpenRC)
3. Build/install components from `sources.conf` 
4. Install zinit as `/sbin/init`
5. Copy zinit configuration from `config/zinit/`
6. Set up 2-stage module loading infrastructure
7. **Aggressive cleanup**: remove docs, locales, headers, apk cache
8. **Strip and UPX all binaries** in initramfs tree only
9. Create `initramfs.cpio.xz`

#### **Component Build System**
- Each component type (git/release) has specific build function
- Build in `components/` directory, install to `initramfs/`
- Support custom build functions defined in `components.sh`
- Handle dependencies between components

### **Code Structure Requirements**

#### **Bash Scripting Standards**
- **Modular design**: Each problem domain = separate sourced file
- **Function naming**: Prefix with domain (`docker_start_container`, `alpine_install_packages`)
- **Error handling**: `set -euo pipefail` in all scripts, script must stop on ANY error
- **NO SILENT ERRORS**: All commands must be verified for success
- **Command echoing**: Every command must be echoed with full parameter expansion before execution
- **Logging**: Standardized logging with timestamps and levels
- **NO GLYPHS OR ICONS**: Use plain text separators, titles, and lines only
- **Sourcing pattern**: Main script sources lib functions as needed

#### **Command Execution Pattern**
Every command must follow this pattern:
```bash
echo "Executing: command arg1 arg2 ${variable}"
command arg1 arg2 "${variable}"
if [ $? -ne 0 ]; then
    echo "ERROR: Command failed: command arg1 arg2 ${variable}"
    exit 1
fi
```

#### **Section Separation Pattern**
Use clear text separators like:
```bash
echo "=================================================="
echo "SECTION: Building Components"
echo "=================================================="
```

#### **Function Categories Required**
```bash
# docker.sh
docker_build_container()
docker_start_rootless()
docker_commit_builder()

# alpine.sh  
alpine_extract_miniroot()
alpine_install_packages()
alpine_aggressive_cleanup()

# components.sh
components_parse_sources_conf()
components_download_git()
components_download_release()
components_build_all()

# initramfs.sh
initramfs_setup_zinit()
initramfs_setup_modules()
initramfs_strip_and_upx()
initramfs_create_cpio()

# kernel.sh
kernel_download_source()
kernel_apply_config()
kernel_build_with_initramfs()

# testing.sh
testing_qemu_boot()
testing_cloud_hypervisor_boot()
```

### **Error Handling Requirements**
- **Strict mode**: `set -euo pipefail` in every script
- **Command verification**: Check exit code of every command
- **Explicit failures**: No silent failures or ignored errors
- **Cleanup on failure**: Provide cleanup functions for partial builds
- **Detailed error messages**: Include command that failed and context

### **zinit Integration Specifications**
- Replace `/sbin/init` completely
- Create service definitions for:
  - Stage 2 module loading
  - Network initialization
  - Serial getty (for testing)
  - Basic system services
- No OpenRC compatibility layer needed

### **Testing Requirements**
- QEMU command with proper serial console
- cloud-hypervisor alternative command
- Serial console properly configured for zinit getty
- Boot process should reach serial login prompt

### **GitHub Actions Compatibility**
- Rootless container execution
- No privileged operations required
- Cacheable build steps
- Artifact generation (vmlinuz.efi, build logs)

### **Documentation to Include**
- subuid/subgid setup instructions
- Container runtime requirements
- Configuration file documentation
- Testing procedure
- GitHub Actions integration example

## **Deliverables**
1. Complete bash script framework with all functions
2. Sample configuration files (packages.list, sources.conf, etc.)
3. Basic zinit service definitions
4. Container setup and build orchestration
5. Testing commands for QEMU/cloud-hypervisor
6. Documentation for setup and usage

## **Constraints**
- Pure bash scripting (no Python/other languages)
- Rootless container compatible
- GitHub Actions compatible
- Reproducible builds
- No OpenRC dependencies
- Aggressive size optimization
- **NO GLYPHS, ICONS, OR UNICODE DECORATIONS**
- **ECHO EVERY COMMAND WITH PARAMETER EXPANSION**
- **VERIFY EVERY COMMAND EXECUTION**
- **STOP ON ANY ERROR**

**Start by creating the complete directory structure and all bash script files with function stubs and proper sourcing patterns. Include the command echoing and error checking patterns in every function. Then implement each function systematically with strict error handling.**