wndrks

tools/msix/README.md

@@ -0,0 +1,120 @@
+# MSIX publish workflow
+
+This folder contains the scripts used to build the MSIX package, flatten the
+App Installer deployment files, upload them to the Synology NAS web folder, and
+verify the public download URLs.
+
+## Files
+
+- `Publish-MsixToNas.ps1`: builds the app package, stages the deployable files,
+  uploads them to the NAS with SSH/SCP, and verifies the public URLs.
+- `Install-ComtrophyMsixCertificate.ps1`: installs the MSIX signing certificate
+  for the current Windows user, then optionally opens the appinstaller URL.
+
+## First-time NAS SSH setup
+
+1. Create or choose a NAS user that can write to `/volume1/web/msix`.
+2. Enable SSH on the Synology NAS.
+3. Optional but recommended: create an SSH key for publishing.
+
+```powershell
+ssh-keygen -t ed25519 -f $env:USERPROFILE\.ssh\nas_msix_ed25519
+type $env:USERPROFILE\.ssh\nas_msix_ed25519.pub
+```
+
+Add the printed public key to the NAS user's `~/.ssh/authorized_keys`.
+
+Test the connection:
+
+```powershell
+ssh -i $env:USERPROFILE\.ssh\nas_msix_ed25519 <nas-user>@192.168.200.129 "ls -ld /volume1/web/msix"
+```
+
+## Publish a new build
+
+Set the NAS login once in the current PowerShell session:
+
+```powershell
+$env:NAS_USER = "<nas-user>"
+$env:NAS_SSH_KEY = "$env:USERPROFILE\.ssh\nas_msix_ed25519"
+```
+
+Build, package, upload, and verify:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\msix\Publish-MsixToNas.ps1 -Configuration Release -IncrementPackageRevision
+```
+
+Use `-IncrementPackageRevision` for normal approved deployments. It reads the
+current `Package.appxmanifest` version and increments the fourth version part
+before building. App Installer uses the MSIX package version to decide whether a
+client should receive an update.
+
+In Codex sessions, this is the command to run only after the user explicitly
+approves publishing the finished work.
+
+To publish a specific version instead:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\msix\Publish-MsixToNas.ps1 -Configuration Release -PackageVersion 1.0.3.2
+```
+
+To upload the latest already-built package without rebuilding:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\msix\Publish-MsixToNas.ps1 -Configuration Debug -SkipPackageBuild
+```
+
+To prepare files locally without uploading:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\msix\Publish-MsixToNas.ps1 -Configuration Debug -SkipPackageBuild -NoUpload
+```
+
+The default public base URL is:
+
+```text
+http://122.34.248.185/msix/
+```
+
+If the deployment should use the Synology DDNS name instead, pass:
+
+```powershell
+-PublicBaseUri "http://comtropy.synology.me/msix/"
+```
+
+## Installer link
+
+After publish, the installer URL is:
+
+```text
+http://122.34.248.185/msix/Tornado3_2026Election_x64.appinstaller
+```
+
+The user PC must trust the signing certificate before installing the MSIX for
+the first time. The script only installs the certificate; it does not run the
+app installer. Approve the UAC administrator prompt when Windows asks:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\Install-ComtrophyMsixCertificate.ps1
+```
+
+To run it directly from the NAS on a target PC:
+
+```powershell
+$script = Join-Path $env:TEMP "Install-ComtrophyMsixCertificate.ps1"
+Invoke-WebRequest "http://122.34.248.185/msix/Install-ComtrophyMsixCertificate.ps1" -OutFile $script
+powershell -ExecutionPolicy Bypass -File $script
+```
+
+After the certificate setup is complete, open the appinstaller link once to
+install the app. After installation, run the app from the Windows Start menu, not
+from the appinstaller link.
+
+If installation fails with `0x800B0109`, confirm the certificate is present in
+both local computer stores:
+
+```powershell
+Get-ChildItem Cert:\LocalMachine\TrustedPeople, Cert:\LocalMachine\Root |
+    Where-Object Thumbprint -eq "E691A33C64DF20A204FFD4F096B9C3EB4B95709C"
+```