server-deploy/internal/preflight/README.md

Read-only local environment proposal

deployctl preflight takes no stdin request. It collects facts from the local machine and emits protocolVersion, mode=local-environment-proposal, observedAt, report and proposal. It never connects to SSH/Docker, runs package managers, sources shell files, writes configuration or starts/restarts services.

Observations

• Reuses inspect for OS, architecture and systemd/Docker-client file presence.
• Reads only ID, VERSION_ID and VERSION_CODENAME from /etc/os-release, at most 64 KiB. Handles plain and simply quoted values, not a shell grammar. Ambiguous, duplicated, missing or unsupported value syntax fails closed. Other keys are ignored, not evaluated or returned. Trusted host files/ancestors are assumed.
• Linux effective UID is classified root/non_root/unknown.
• Linux statfs reports available bytes on the filesystem containing /var/lib. This does not measure another configured data root, quotas, or inode capacity. Unknown disk observations cannot authorize a fresh-install candidate.
• Resource checks inspect directory entries for /var/lib/docker, /var/lib/containerd, /etc/docker, /var/lib/server-deploy, and the Docker .sources/.list paths under /etc/apt/sources.list.d. Contents are not read. Any link or non-directory intermediate component is treated as existing; access failures become unknown, not absent. Checks are conservative hints, not a complete scan of runtime installations or APT sources.
• Non-Linux hosts do not read Linux paths or report Linux disk availability.
• Reads a bounded local dpkg status snapshot and requires an empty update journal. Reports only the Docker/runtime-related package records and the complete status file digest. Missing/malformed/journal-busy input is unknown, not an empty host. Installed, held, partial and residual relevant records all require manual review. It does not audit unrelated dependency health or non-dpkg installations.

Candidate policy

Linux amd64/arm64; Ubuntu version/codename pairs 22.04/jammy, 24.04/noble, 26.04/resolute; root; systemd path present; at least 5 GiB available on /var/lib; Docker client absent; all listed resource paths observed absent. The 5 GiB floor is only a bootstrap screening threshold, not a calculated application/image/backup capacity requirement. Docker official Ubuntu support was checked at implementation: Docker installation requirements. This project has not certified these distributions with actual installation tests.

If all these observations pass, proposal lists candidate source configuration, version-locked package installation and engine/Compose verification steps, plus APT/disk/service-start/firewall impacts. It does not produce shell commands or claim those steps can yet execute. Existing resources cause manual-review blockers; there is no automatic removal, adoption, migration or package conflict cleanup.

Every proposal remains executable=false, with blockers for unverified host identity, unknown package inventory, unresolved versions, repository trust, network/firewall and the unimplemented installer. Empty candidate steps mean preliminary host observations also failed. Nonempty steps are NOT an approved install transaction.

Reports describe this process's environment (possibly a container/WSL instance), not necessarily the intended cloud server. No snapshot hash, SSH identity binding, freshness token or lock-based revalidation exists yet. These must be implemented before any future write path consumes observations. Exit 0 means a report was produced; inspect proposal.blockers, never exit status alone, for readiness.