zscripts-token-savers/zrepair.ps1
kellymichels 91b638ac31
feat: checksums, toolkit versioning (v{major}.{rc}.{beta}.{alpha}.{build}), and downloadable release zips (#35)
* feat(zchecksums): SHA-256 manifest so a download can be verified before it's run

CHECKSUMS.txt lists a SHA-256 for every top-level .ps1 and .cmd - the files a
user actually executes. zchecksums verifies them; zchecksums -Update
regenerates after an intentional edit.

The manifest is sha256sum format, so 'sha256sum -c CHECKSUMS.txt' works on
Linux/macOS/WSL as well as the PowerShell path on Windows. Hashes are identical
on every platform because .gitattributes pins .ps1/.cmd to CRLF everywhere -
that pin is now load-bearing, so it is commented as such.

Beyond changed and missing files it also reports a script that is on disk but
NOT in the manifest, so something added outside a commit still gets noticed.
Exits non-zero on any of the three.

Honest about its limits, in the header and the README: the manifest lives in
the same repo as the code, so it is an integrity check rather than a signature.
It catches a truncated clone, a forgotten local edit, or an unlisted file - not
a compromised repo.

CHECKSUMS.txt is pinned to LF: sha256sum treats a trailing CR as part of the
filename and would report every entry as missing on Linux.

tests/Checksums.Tests.ps1 keeps it from rotting - a stale manifest is worse
than none, since it either cries wolf until people ignore it or quietly stops
covering a new script. The tests assert the format, LF endings, sort order,
full coverage of on-disk scripts, current hashes, and that zchecksums itself
exits 1 on a tampered file (proved by appending a byte and restoring it).

* feat(zversion, zrelease): toolkit versioning + downloadable release zips

Implements the versioning rule (SmartPlant's 5-segment scheme, now the global
standard; currently only sp and zscripts are on it at v1.x):

    v{major}.{rc}.{beta}.{alpha}.{build}

zversion: get / bump / bump-stage / set. A stage bump zeroes every lower
segment including build. 'bump' is one per PR and one per defect fix, not per
file. Any write rewrites three things together, because they are only useful
when they agree: build-version.json (source of truth), a '# Version:' line in
all 42 script headers (a lone copied script still says which release it came
from), and CHECKSUMS.txt (stamping changes every file).

zrelease: packages the current version as releases/zscripts-<version>.zip with
a sibling .sha256, for people who want the toolkit without cloning. One hash
verifies the download; the bundled CHECKSUMS.txt verifies the extracted
contents. Refuses to overwrite an existing version's zip (released = immutable;
bump instead), and refuses to package when zchecksums fails. tests/ excluded
from the zip; releases/ never packages itself.

First release included: releases/zscripts-v1.0.0.0.0.zip (42 scripts + 7
support files) and its .sha256.

.gitattributes: releases/*.sha256 pinned LF (sha256sum treats a trailing CR as
part of the filename), releases/*.zip marked binary.

Verified end-to-end as a downloader would experience it, in WSL: sha256sum -c
on the zip passes, unzip, sha256sum -c CHECKSUMS.txt inside gives 42 OK / 0
FAILED, and the extracted zdeploy.ps1 header and build-version.json both read
v1.0.0.0.0. Double-release guard and -Verify mode exercised. Full Pester suite
219/219 (the checksum tests absorb the new files automatically).
2026-07-28 13:47:25 -05:00

105 lines
3.8 KiB
PowerShell

# Evomedia.net Token Savers — https://github.com/kellymichels/zscripts-token-savers
# Created by Kelly Michels · dev@evomedia.net
# Licensed under the MIT License. See LICENSE.
# Version: v1.0.0.0.0
# zrepair.ps1 — audit and repair container/proxy routing on the server, then smoke test.
#
# Usage:
# zrepair <project> [<project> ...]
#
# For each project: shows compose status, starts the stack if it's down,
# validates the edge proxy's nginx config (once, if an edge project is defined),
# and smoke-tests the live domain.
#
param(
[Parameter(Position = 0, ValueFromRemainingArguments = $true)]
[string[]]$Projects = @()
)
$ErrorActionPreference = "Stop"
. (Join-Path $PSScriptRoot "ZHelpers.ps1")
Start-ZTracking
$cfg = Get-ZConfig
$EC2_IP = $cfg.ec2.ip
if ($Projects.Count -eq 0) {
$keys = (Get-ZProjectKeys) -join ', '
Write-Host ""
Write-Host "Usage: zrepair <project> [<project> ...]" -ForegroundColor Yellow
Write-Host " Projects in zconfig.json: $keys" -ForegroundColor Gray
Stop-ZTracking; exit 1
}
Write-Host ""
Write-Host "=== Routing repair & diagnostics ===" -ForegroundColor Cyan
Write-Host "Target host: $EC2_IP" -ForegroundColor Gray
# Validate the edge proxy config once up front, if one is defined.
$edgeProj = Get-ZEdgeProject
if ($edgeProj -and $edgeProj.Config.proxyContainer) {
$pc = $edgeProj.Config.proxyContainer
Write-Host ""
Write-Host " [edge] Validating nginx config in proxy container '$pc'..." -ForegroundColor Yellow
Invoke-Ec2Step -Label "nginx -t in $pc" -Bash "sudo docker exec $pc nginx -t 2>&1"
}
foreach ($key in $Projects) {
$proj = Get-ZProject -Key $key
$composeDir = Get-RemoteComposeDir -Key $key
Write-Host ""
Write-Host "=========================================" -ForegroundColor Cyan
Write-Host "=== Repairing $($proj.label) ($key) ===" -ForegroundColor Cyan
Write-Host "=========================================" -ForegroundColor Cyan
Write-Host ""
Write-Host " [1/3] Compose status on the server..." -ForegroundColor Yellow
$statusBash = @"
cd $composeDir || exit 1
echo "Running containers:"
sudo docker compose ps
"@
Invoke-Ec2Step -Label "Check compose status" -Bash $statusBash
Write-Host " [2/3] Ensuring stack is up..." -ForegroundColor Yellow
$ensureBash = @"
cd $composeDir || exit 1
if ! sudo docker compose ps | grep -q "Up"; then
echo " [Action] Stack is down. Starting..."
sudo docker compose up -d
else
echo " [OK] Stack is active and UP."
fi
"@
Invoke-Ec2Step -Label "Ensure stack is up" -Bash $ensureBash
if ($proj.domain) {
Write-Host " [3/3] Smoke test for https://$($proj.domain)..." -ForegroundColor Yellow
try {
$resp = Invoke-WebRequest -Uri "http://$EC2_IP/" -Headers @{ Host = $proj.domain } -UseBasicParsing -TimeoutSec 15 -MaximumRedirection 5
$status = [int]$resp.StatusCode
if ($status -ge 200 -and $status -lt 400) {
Write-Host " PASS - responded with HTTP $status (Online)" -ForegroundColor Green
} else {
Write-Host " WARNING - unexpected HTTP $status" -ForegroundColor Yellow
}
} catch {
$status = $_.Exception.Response.StatusCode.value__
if ($status -ge 200 -and $status -lt 500) {
Write-Host " PASS - responded with HTTP $status (Online/Redirect)" -ForegroundColor Green
} else {
Write-Host " FAIL - smoke test failed: $($_.Exception.Message)" -ForegroundColor Red
}
}
} else {
Write-Host " [3/3] No domain configured - skipping smoke test." -ForegroundColor DarkYellow
}
}
Write-Host ""
Write-Host "=== Repair & diagnostics completed ===" -ForegroundColor Green
Write-Host ""
Stop-ZTracking