From d6be456c39b586759e76fdd2f0b3a40d1ce423bd Mon Sep 17 00:00:00 2001 From: Stefan Strobl Date: Wed, 24 Dec 2025 09:50:14 +0100 Subject: [PATCH] feat(core): add phase 1 narrative for core orchestration modules Add literate programming phase 1 documentation for: - main.sh: wrapper orchestration and user journey - config.sh: configuration management and defaults - sanity.sh: preflight safety checks Decision: UEFI-only support to reduce complexity. BIOS would require separate /boot partition and additional testing burden disproportionate to modern hardware usage. Decision: LUKS2 as default encryption for improved security tooling, with clear guidance for LUKS1 fallback if GRUB boot fails. Auto-detection rejected due to version fragmentation. Decision: Interactive configuration as default. Presets are out of scope for phase 1 to keep the flow understandable. The user journey documents the complete end-to-end flow from live medium boot to first encrypted boot, establishing clear handoff points between wrapper and installer. --- src/config.sh | 31 +++++++++++++++++++++++++++++++ src/main.sh | 43 +++++++++++++++++++++++++++++++++++++++++++ src/sanity.sh | 25 +++++++++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 src/config.sh create mode 100644 src/main.sh create mode 100644 src/sanity.sh diff --git a/src/config.sh b/src/config.sh new file mode 100644 index 0000000..03c24b1 --- /dev/null +++ b/src/config.sh @@ -0,0 +1,31 @@ +# === Motivation === +# Centralize user-provided inputs to avoid scattered magic values. +# === Problem Statement === +# Disk targets, encryption mode, filesystem choice, and host metadata need a single source of truth. +# === Scope === +# In scope: definition of configurable parameters and validation expectations. +# Out of scope: parsing implementation and storage mechanism. +# === Concepts === +# Preset: a named set of config values for repeatable installs. +# Interactive input: prompting the user for values at runtime. +# === Decisions === +# Keep defaults conservative and require explicit confirmation for destructive values. +# Surface all critical values before any destructive phase begins. +# Default to LUKS2 with an explicit LUKS1 fallback for bootloader compatibility. +# Default filesystem is btrfs, with opt-in alternatives. +# Default bootloader is GRUB for Void compatibility. +# Passphrase-only is the supported unlock method. +# Swap defaults to a file (works with both btrfs and ext4). +# Mandatory values are DISK, HOSTNAME, and size inputs where no safe default exists. +# Interactive prompts are the default input mechanism; no preset formats are defined yet. +# === Alternatives Considered === +# Hard-coded values rejected because they do not scale across machines. +# === Constraints === +# Config must be readable and editable without specialized tools. +# Target boot mode is UEFI only; BIOS is out of scope. +# === Open Questions === +# Should we support config file presets for batch installations, or keep it fully interactive? +# How should we validate user-provided disk paths to prevent typos? +# Should swap size have intelligent defaults based on RAM size, or always ask? +# === Success Criteria === +# Users can clearly see and confirm target disk, encryption type, and filesystem choice. diff --git a/src/main.sh b/src/main.sh new file mode 100644 index 0000000..523a1f3 --- /dev/null +++ b/src/main.sh @@ -0,0 +1,43 @@ +# === Motivation === +# Provide a reproducible wrapper around the Void installer for encrypted setups. +# Reduce manual, error-prone steps while keeping user control over installer choices. +# === Problem Statement === +# The stock installer does not automate disk preparation for encrypted layouts. +# We need a guided wrapper that prepares the target disk before the installer runs. +# === Scope === +# In scope: orchestration of phases, user confirmations, mode selection. +# Out of scope: replacing the official installer UI, package selection, BIOS support. +# === Concepts === +# Wrapper: a script that executes pre-install tasks then hands off to the installer. +# Phases: sanity, disk layout, encryption, filesystems, mounts, installer, post-install. +# === User Journey === +# 1. User boots Void live medium and runs the wrapper script. +# 2. Sanity checks validate environment (UEFI mode, root privileges, target disk exists). +# 3. User provides configuration: target disk, encryption mode, filesystem choice, hostname. +# 4. User reviews planned layout, encryption settings, and filesystem choices. +# 5. User confirms destructive operation with explicit disk identifier confirmation. +# 6. Wrapper prepares disk: partition → encrypt → format → mount. +# 7. Wrapper pauses and instructs user to run official installer using existing mounts. +# 8. User completes installer, selecting packages and configuring system preferences. +# 9. After installer exits, wrapper performs post-install configuration (crypttab, dracut, GRUB). +# 10. User reboots into encrypted Void system, enters passphrase at boot. +# === Decisions === +# Keep the official installer in the loop because it handles system configuration choices. +# Prefer a phase-based flow to make recovery and retries understandable. +# Target x86_64 only to keep the scope focused. +# Default to a UEFI-first flow with an ESP. +# Start with a fully interactive flow; presets are out of scope for now. +# Provide a dry-run mode to review planned actions before execution. +# === Alternatives Considered === +# Full automation without the official installer rejected due to maintenance burden. +# Manual instructions only rejected because they remain error-prone. +# === Constraints === +# Must be safe for destructive operations and require explicit confirmation. +# Must support UEFI boot flow; BIOS is out of scope. +# === Open Questions === +# Should the wrapper support resuming from a failed phase, or always start from scratch? +# How should the wrapper handle pre-existing partitions on the target disk? +# Should the dry-run mode generate a detailed execution plan, or just show configuration summary? +# === Success Criteria === +# A user can run the wrapper, confirm disk intent, and reach the installer with correct mounts. +# The narrative of each phase is clear enough to audit and adapt. diff --git a/src/sanity.sh b/src/sanity.sh new file mode 100644 index 0000000..93fc65f --- /dev/null +++ b/src/sanity.sh @@ -0,0 +1,25 @@ +# === Motivation === +# Prevent catastrophic mistakes before any disk operations. +# === Problem Statement === +# The wrapper must ensure it is running in a safe context with the intended target. +# === Scope === +# In scope: checks for privileges, environment, and target disk presence. +# Out of scope: detailed hardware inventory. +# === Concepts === +# Preflight: a set of checks that must pass before continuing. +# === Decisions === +# Fail fast on missing privileges or ambiguous disk selection. +# Require a typed confirmation of the target disk identifier. +# Reject unsupported architectures; x86_64 is the only supported target. +# Reject non-UEFI boot modes; BIOS systems are out of scope. +# Provide a dry-run mode to review planned actions before execution. +# === Alternatives Considered === +# Proceeding with warnings only rejected due to data loss risk. +# === Constraints === +# Checks must run without relying on network access. +# === Open Questions === +# Should we check for minimum disk size requirements before proceeding? +# How do we detect if the system was booted in UEFI mode reliably? +# Should we warn if the target disk contains existing partitions, or just require explicit confirmation? +# === Success Criteria === +# The wrapper refuses to proceed if the target disk is unclear or unsafe.