feat: add deployment foundation and cross-device handoff

2026-09-25 08:49:19 +08:00
parent 8ccb8b7c15
commit e965b0943d
77 changed files with 8018 additions and 0 deletions
@@ -0,0 +1,57 @@
+# 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](https://docs.docker.com/engine/install/ubuntu/).
+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.