staging: add vm-lab - Photon OS VM provisioning for VMware Workstation

staging/README.md

@@ -4,6 +4,22 @@ This subdirectory contains early scripts and prototypes kept for staging purpose
 
 ## Contents
 
+### vm-lab/
+End-to-end provisioning of a Photon OS VM on VMware Workstation: the VMX
+template (every non-default key annotated with the failure it prevents), the
+boot VMDK, the kickstart, an unattended install, SSH access, teardown, and the
+verification scripts that say whether each stage actually did what it claims.
+Defaults to **2 vCPU / 4 GB RAM / 50 GB thin disk in a single file**
+(`monolithicSparse` — the size is a ceiling, not an allocation: a fresh disk
+is ~6 MB and grows on use). Overridable per run.
+
+Two things it documents that are easy to lose a day to: SSH access is decided
+at **ISO build time** (the key variables default to empty, so a normal build
+ships an empty `authorized_keys` and a locked root), and the install CDROM must
+be on SATA because the `linux-mok` kernel has no IDE CDROM driver. See
+[vm-lab/README.md](vm-lab/README.md); provenance and the kickstart-drift check
+are in [vm-lab/PROVENANCE.md](vm-lab/PROVENANCE.md).
+
 ### install-sizes-calc/
 Package install size estimation for Photon OS, organized into two approaches:
 - **shell-based/** -- `DynamicSizeCalculation.sh`: A Bash script that uses `tdnf repoquery` and `tdnf info` to query installed package sizes without downloading, then calculates totals with a configurable buffer and compression ratio estimate.

staging/vm-lab/.gitattributes

@@ -0,0 +1,24 @@
+# Line endings are load-bearing here.
+#
+# The shell scripts run under WSL/Linux. If a Windows checkout with
+# core.autocrlf=true gives them CRLF, bash fails on the very first line with
+#     $'\r': command not found
+# which is a confusing way to learn about line endings. Pin them to LF so the
+# scripts work straight out of a checkout on either platform, without the
+# `tr -d '\r' < script > /tmp/x.sh` dance.
+*.sh            text eol=lf
+*.env           text eol=lf
+*.json          text eol=lf
+EXPECTED-SHA256 text eol=lf
+
+# The VMX template is read by PowerShell, which normalises to CRLF itself when
+# it writes the real .vmx (VMware wants CRLF). The template can stay LF.
+*.template      text eol=lf
+
+# PowerShell scripts are Windows-native; CRLF is what an editor there expects.
+# NOTE: these files are deliberately ASCII-only - Windows PowerShell 5.1 reads
+# .ps1 as ANSI unless the file has a UTF-8 BOM, so a non-ASCII character
+# corrupts a string literal and yields a cascade of misleading parse errors.
+*.ps1           text eol=crlf
+
+*.md            text

staging/vm-lab/PROVENANCE.md

@@ -0,0 +1,55 @@
+# Provenance
+
+`staging/vm-lab/` is a snapshot of `deploy/vm-lab/` from the SPAGAT-Librarian
+appliance repository.
+
+```
+source repo   : dcasota/SpagatLibrarian-Appliance
+source path   : deploy/vm-lab/
+authored at   : b7ec6954e03ebe1c1b134bd5d8267c402848bdb0
+snapshot date : 2026-08-31
+```
+
+**What that commit id means.** `deploy/vm-lab/` was authored alongside
+`b7ec6954` but is not itself committed in the source repo yet, so
+`photonos-scripts/staging/vm-lab/` is currently its published home. The id
+identifies the appliance tree these scripts were written and tested against —
+in particular the kickstart template and the `spagat-vm-orchestrator` CLI
+surface they wrap — not a commit that contains this directory.
+
+## The kickstart copy
+
+`kickstart/photon-appliance.ks.template.json` is a **byte-exact** copy of
+`src/tools/iso-build/iso-phase6-kickstart-template.cfg` in the source repo,
+which is the file the ISO build actually consumes.
+
+```
+sha256 at snapshot time: ac5a3a5c3f87e392af927d070052f0edf86d178fb70a427e51fef4572c67f7e1
+```
+
+`kickstart/check-drift.sh` verifies this and states which mode it used:
+
+- **Mode 1** — a SPAGAT checkout is reachable (`SPAGAT_REPO=/path/to/repo`, or
+  this directory sitting inside that repo): it diffs against the live
+  canonical file and catches drift in **either** direction.
+- **Mode 2** — standalone, as here: it falls back to the hash above. That
+  still detects an edited local copy, but **cannot** tell you whether the
+  upstream template has moved on. The script says so rather than implying it
+  proved more than it did.
+
+If neither the canonical file nor `EXPECTED-SHA256` is available it exits
+non-zero — "cannot check" must never read as "fine".
+
+A convenience copy that can silently diverge from the real thing is worse than
+no copy, because you would reason about a kickstart the build never uses.
+
+## Refreshing the snapshot
+
+```bash
+SPAGAT=/path/to/SpagatLibrarian-Appliance
+cp "$SPAGAT/src/tools/iso-build/iso-phase6-kickstart-template.cfg" \
+   staging/vm-lab/kickstart/photon-appliance.ks.template.json
+sha256sum staging/vm-lab/kickstart/photon-appliance.ks.template.json \
+   | cut -d' ' -f1 > staging/vm-lab/kickstart/EXPECTED-SHA256
+# then update the sha256 and the commit id above
+```