Mirror of the same change in the private scripts repo: [Console]::OutputEncoding is switched to UTF-8 (no BOM) around the deploy loop and restored in a finally. PowerShell 5.1 decodes ssh's stdout with the OEM code page, where the UTF-8 bytes of a progress bar read as three characters each.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Build stamp catch-up for 4 merged PR(s) since v1.0.0.0.27:
b26be3c chore: write the site name as evomedia.net, lowercase (#92)
22a7387 feat(site): link preview for zscripts.evomedia.net, with a card in the page's own colours (#91)
86938d0 chore: publish the zec2 and zec2online comment updates to the mirror (#87)
90f4301 fix: pin the .txt twins to LF so regenerating them stops reporting a change (#89)
* chore: write the site name as evomedia.net, lowercase
The name is a domain and is written as one. Script headers, the README,
CHANGELOG and elevator pitch, their .txt twins, and the site page --
matching the same sweep in the private evo.scripts so the mirror does not
drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore: refresh CHECKSUMS.txt for the lowercase sweep
Every script's header changed, so every hash did. The repo's own
Checksums test caught it -- which is what it is for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The page had a title and a description and nothing else, so pasting the link
anywhere rendered a bare URL.
- the full og:* block with absolute URLs, plus twitter:card and a canonical the
og:url agrees with
- site/og-card.png, 1200x630, in the page's own dark palette so the preview and
the page look like the same thing. Composed by make_og_card.py in the private
tooling repo; it lives in site/ because that directory is what reaches the
server.
- tests/LinkPreview.Tests.ps1
The last test is the one that earned its place. The first draft of the card
showed `ztests`, which is not a command in this repo - so the test extracts the
z-commands named in og:image:alt and fails unless each one is a real .ps1 or
.cmd at the root. A card is public copy, and public copy must not advertise a
script that does not exist.
CHECKSUMS.txt is untouched: the manifest covers top-level executables only, and
nothing here is one.
Tested: 6 new tests, verified to fail when the card advertises ztests again.
Full suite 292 passed, 1 skipped.
Closes#90
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* chore: publish the zec2 and zec2online comment updates
Mirror drift, not new behaviour: the private copies had their comments
reworded and the public ones had not caught up.
Two things the new wording carries that the old did not:
zec2 now records WHY it grew an ssh of its own. The container-side version
read referenced three variables the script never defined, and because that
read sits inside a try/catch the failure was silent - it fell through to the
HTTP call and reported nothing once that endpoint stopped being public. A
missing variable and an unreachable service looked identical from the
outside, which is the kind of thing worth writing down next to the fix.
Both files now describe the container-side read by what it is - an endpoint
that is not public on every project - rather than by a product's own
wording, which is what keeps this mirror publishable.
Published with zpublish_zscripts; CHECKSUMS.txt refreshed by the same run
and committed with them, as that script requires.
Tests: 286 passed, 1 skipped across the suite; checksums, plain-text twins
and sanitization re-run after the changelog edit - 70 passed.
README.txt was left out deliberately. Regenerating the twins rewrote it with
LF where the repo stores CRLF, and the content is byte-identical - a no-op
that would only have added noise to this diff.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix: rehash zec2 and zec2online against their checked-out form
CI failed the manifest check on both files. The hashes in CHECKSUMS.txt were
computed from the copies zpublish_zscripts had just written, which land with
LF; .gitattributes pins *.ps1 to eol=crlf, so every checkout - CI's included
- materialises them with CRLF and hashes differently.
Local runs passed because the working tree had already been normalised by a
later git operation. Only CI, checking out clean, saw the mismatch. The new
hashes are byte-for-byte the "But was:" values from the failing run.
Nothing about the scripts changed; this is the manifest catching up with the
form the files actually take on disk after checkout.
Worth noting where the sharp edge is: the manifest is generated from the
working tree, so any tool that writes a pinned file and hashes it in the same
breath records a hash the repo will never reproduce. Re-materialising from
git before hashing is what makes the two agree.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Three things disagreed about line endings, and the generator lost:
stored in git LF
checked out CRLF (core.autocrlf - nothing pinned *.txt)
written by the LF (plaintext_twins.py, newline="\n")
generator
So every run wrote LF over a CRLF checkout, git status reported each twin as
modified, and git add normalized it straight back to LF for an empty diff.
A generator that always reports work hides the one time it did some. It also
puts noise in front of the reviewer on every publish - exactly where a real
change should be easy to see - and trains the reader to discard the twins
without looking, which is how genuine drift gets thrown away.
Pinning *.txt to eol=lf makes checkout agree with both the generator and the
stored form. Verified: regenerate, and only .gitattributes is modified.
CHECKSUMS.txt keeps its own explicit line even though *.txt now covers it.
Its reason is different in kind - sha256sum -c treats a trailing CR as part
of the filename and reports every entry as missing, which is a broken
verification rather than a cosmetic diff - and that should not silently
depend on a glob above it staying where it is.
Closes#88
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Build stamp catch-up for 2 merged PR(s) since v1.0.0.0.26:
c317b13 docs(readme): give the download-and-verify path a PowerShell form (#85)
d4cfa98 feat(site): track the public page this project serves (#84)
"Downloading without cloning" was bash only, in the README of a PowerShell
toolkit. It is also the first thing a stranger does, so the one section aimed
squarely at newcomers was the one they could not run: `sha256sum` and `unzip`
are not Windows commands at all, and `&&` is a parse error in PowerShell 5.1
rather than a wrong result.
PowerShell goes first here, because these commands are PowerShell - Get-FileHash
against the .sha256, Expand-Archive, then zchecksums.cmd for the contents. The
bash form stays below it, matching how "Verifying what you downloaded" already
leads with zchecksums and offers sha256sum second.
Tested against releases/zscripts-v1.0.0.0.9.zip: the comparison returns True.
It also gets a note, because the output invites a wrong conclusion -
Get-FileHash prints upper case and the .sha256 file holds lower, so the two
strings look different side by side. PowerShell's -eq is case-insensitive on
strings, so the check is right and the eyes are wrong.
Twins regenerated; the Pester twin-sync test passes.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
zscripts.evomedia.net has served a page since July that existed in exactly
one place: the landing container on the box. No repo held it, so a rebuild
would not have brought it back and a change to it had no history.
Two fixes while bringing it in:
- Both GitHub buttons pointed at kellymichels/zscripts-token-savers, the
pre-org location. It 301s rather than 404s, so it was not broken - but the
page's primary call to action depended on a redirect that stops working
the day that name is reused. Both now point at evomedia-net/evo.zscripts.
- robots.txt added, allowing everything. The estate's other landing-served
pages disallow everything because they are private candidate pages; this
one is an open-source project's front page and wants to be found.
Sanitization suite passes with the page included - it scans .html, so the
guard that keeps private identifiers out of this mirror now covers the page
as well.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Build stamp catch-up for 1 merged PR(s) since v1.0.0.0.25:
f2e6302 fix(zdeploy): build docker stacks that come from a Dockerfile, instead of restarting the old image (#81)
This repo is public, and the denylist that keeps private identifiers out of it
spelled two of them in full: the retired EHS product name, and its old domain.
The file protecting the name was the file publishing it.
Deleting those two rules was not an option. The private tree still carries that
name in ~20 places - sp_fix_kelly_email_prod.ps1 alone has the old domain and a
real prod stack path - so both rules are live, not stale. Dropping them would
trade a visible string for an actual leak path.
So split the literal with a one-character class instead: Smart[P]lant and
smart[p]lantehs. A class of one matches exactly that character, so the regex is
unchanged - verified by matching both spellings and the old domain before and
after, with negative controls - while the contiguous string no longer appears
in a public file.
Commented in place, because the obvious "tidy-up" is to un-split it.
Pester: tests/Sanitization.Tests.ps1 14 passed, 0 failed.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(zdeploy): build docker stacks that come from a Dockerfile
Mirrors the fix in the private scripts repo; the code is identical in both, only
the config differs.
The docker kind ran `docker compose pull` then `docker compose up -d`. That is
right for a stack of published images and wrong for one built from a Dockerfile
in the tree, where there is nothing to pull. `up -d` builds only when the image
is MISSING, so the first deploy works and every one after it uploads the new
code, starts the old image, and reports success.
A project opts into building with deploy.build, which runs
`docker compose build --pull` so the base image is refreshed at the same time.
Stacks that pull are unaffected.
The example config documents the flag on the docker project, next to the
existing note about startApp, because the failure is silent and nobody goes
looking for a setting they do not know exists.
CHECKSUMS.txt regenerated, since two covered scripts changed.
286 tests pass, 1 skipped.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(checksums): hash the scripts as git checks them out, not as a tool wrote them
CI failed on the two files this branch touches while the same suite passed here.
The manifest was right about the wrong bytes.
.gitattributes pins *.ps1 to eol=crlf, and its comment says why: it makes these
files byte-identical on every platform, which is what lets CHECKSUMS.txt hold
one hash per file rather than one per OS. The edit that added Get-DockerImageStep
was applied by a script that wrote LF, so the working copy stopped matching the
pin. zchecksums then faithfully recorded the LF hashes, and every checkout that
honours .gitattributes - including CI - disagreed.
Nothing was wrong with the committed content: git normalises on the way in, so
the objects were always correct. Only the local working copy and the manifest
taken from it were off.
Re-materialised both files through git so they carry the endings the attribute
pins, then regenerated the manifest from those.
286 tests pass, 1 skipped.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Build stamp catch-up for 6 merged PR(s) since v1.0.0.0.24:
732a448 feat: add zmerge and zpull — fleet-wide PR merging and checkout sync (#79)
573e010 docs(security): security notes, and a twin for every root .md (#78)
3b0194a perf(tests): run each child-process invocation once (#77)
f27f9dc fix(deploy): read the string build stamp, and never compare two unreadable labels (#76)
16c56dc fix(ci): push trigger names master, this repo's default branch, so the workflow runs after a merge (#75)
32e8d74 chore(ci): add a GitHub Actions workflow that lints with PSScriptAnalyzer and runs the Pester suite on Windows (#74)
* feat: add zmerge and zpull
Two commands that were private-only until now. They turned out to be useful
beyond the fleet they were written for, so they are manifested for publication
and removed from the sanitization denylist's private-only list.
zmerge merge every pull request across the org that is genuinely ready -
MERGEABLE/CLEAN and not a draft - re-checking each one immediately
before and after every merge, because merging into a default branch
can conflict a sibling PR in the same repository. Dry run by
default; -Execute or -e merges.
zpull zmerge, then git pull --ff-only in every checkout the merges
affected. Skips a checkout that is dirty or is not on its default
branch rather than guessing at it.
WHY THEY COULD BE PUBLISHED NOW. zmerge carried a hardcoded list of sixteen
repository names, which was both the reason it could not be published and a
bug: the org has thirty active repositories, so it scanned about half and
reported "Nothing open to merge" while a ready pull request sat in one it had
never heard of. It asks GitHub now, and the names went with the list.
Get-FleetRepos throws rather than returning an empty list when gh fails,
because a tool that quietly scans nothing prints the same reassuring line as
one that scanned everything and found nothing.
-e is an alias for -Execute on both, the way -s already works for -Scan.
Also: __pycache__/ is gitignored. scripts/plaintext_twins.py creates it on
every run and it was showing up as untracked work.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix: CRLF the new scripts, as .gitattributes pins them
zmerge.ps1, zpull.ps1 and zpull.cmd went in with LF endings. .gitattributes
pins *.ps1 and *.cmd to eol=crlf precisely so CHECKSUMS.txt can hold one hash
per file rather than one per platform - so git handed CI a CRLF checkout while
the manifest carried hashes taken from my LF copies, and the three new files
were the only ones that failed.
Local verification passed and CI did not, which is the tell: the manifest was
generated against bytes that only existed on this machine.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Defers to the org policy for how to report and covers what is particular to a
repository that is a sanitised mirror: the most valuable report here is not a
crash, it is something REAL that should not be here - a credential, an internal
hostname, an operator path, an identifier naming a private project. Mail those
rather than filing an issue, because a public issue about a leaked secret
publishes it a second time.
It also says what the automated check is and is not. The sanitisation suite is
a DENYLIST: it proves the absence of known patterns, not the absence of
secrets. Green tests are why a human report is still worth sending.
And the ordinary warning for what these actually are - automation that
archives a tree, uploads it, rebuilds containers and restarts services. Read
before running, nothing here is a sandbox, the config is yours to replace.
TWINS ARE NOW DISCOVERED, NOT LISTED. PAIRS was hand-kept and two files had
outgrown it: ELEVATOR_PITCH.md and TOKEN_SAVINGS.md had no twin at all. Adding
a document and remembering to add it to a list are two acts, and the second is
the one that gets skipped.
The Pester test had the same shape in reverse - it scraped PAIRS out of the
generator's source, so it could only prove the list was self-consistent and a
document nobody listed was invisible to it. It now asks the REPOSITORY what
markdown it has. Proven by deleting SECURITY.txt and watching two tests fail.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Every Invoke-ZScript call starts a fresh Windows PowerShell, which costs about
1.7 seconds - and it is the dominant cost of this file. Thirteen of its
forty-three calls re-run a command an earlier check has already run. The usage
tests are the clearest case: a script is run bare three separate times to
assert that it exits non-zero, that its usage lists the project keys, and that
the usage never mentions the underscore comment key. Those are three questions
about one run.
Memoised on the exact command, so each distinct invocation happens once and
every check that asks for it gets the same captured result. The commands
reached here either refuse their input or inspect an unused fixture port, so
none has a side effect a second run would reveal.
ArgumentParsing.Tests.ps1, over three runs each: 83/108/88s before,
61/68/79s after. All 42 tests still pass.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Get-LabelFromBuildJsonObj knew two stamp shapes and not the third - the string
form the versioning scheme specifies and zbump writes. It fell through to the
legacy branch, where productVersion is null ("") and buildNumber is null (0),
so every string stamp became "v.0".
Deploy verification runs BOTH sides through this function: the local stamp and
the one read back from the running container. So it did not fail loudly - it
collapsed both to "v.0", compared them equal, and printed PASS:
local 'v1.0.0.0.0' -> 'v.0' remote 'v9.9.9.9.9' -> 'v.0' equal? True
A check that cannot fail is worse than no check, because it is believed. It
would report PASS against a container serving a build from weeks ago, which is
the exact case it exists to catch.
- The string form is read first: a stamp that states its version means it,
even if it also carries stray numeric fields from a half-migration. A
missing leading v is tolerated so all three shapes stay comparable.
- The legacy branch returns $null when there is nothing to build a label from,
so a caller sees "no label" instead of a label matching every other
unreadable stamp.
- zdeploy refuses to verify an unreadable local label, and never treats a null
remote label as a match - otherwise $null -eq $null restores the same
vacuous pass one level up.
CHECKSUMS.txt regenerated, since both covered files changed.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The workflow was written with `branches: [main]` like the other two added
the same day, but evo.zscripts' default branch is master, so the push
trigger could never fire here - the PR trigger ran and passed, the merge
to master ran nothing, and the "tests" badge would have stayed at the
PR's result forever. Caught when the post-merge run was looked for and
did not exist.
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
* chore(ci): run the Pester suite on push and pull request
This repo is one of the twelve on the fleet board and had no CI at all, so
the only thing ever running these tests was one workstation at 04:00 - and
on 2026-09-09 that run did not happen, which is how the gap surfaced.
windows-latest rather than ubuntu: Pester runs on Linux, but these scripts
deploy from a Windows workstation and the suite reads like it. Proving them
on Linux would prove something nobody runs.
Pester pinned to 5.x, since the suite uses the v5 configuration API and the
Windows image carries a v3 that would otherwise be picked first, and
-CI so a red suite fails the job - Invoke-Pester on its own exits 0.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore(ci): lint with PSScriptAnalyzer before the Pester suite
PSScriptAnalyzer is the PowerShell linter, and there is no typecheck for
PowerShell, so it is the whole of that half. Errors fail the job; warnings
are printed and do not - the repo was written without the analyzer, and a
gate that goes red on day one over style becomes a gate someone disables.
PSAvoidUsingWriteHost is excluded outright: these are command-line tools
whose Write-Host output is the interface.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The mirror carries the tagOnDeploy feature, its tests, and the zstart
gitPull fix from the private tree. Twelve published references to
current product names and internal issue numbers are reworded
generically, the denylist learns the current spellings (a dot or hyphen
broke the word, an underscore hid the boundary), and planted cases prove
the suite now sees them. CHECKSUMS.txt regenerated.
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Regenerated in a clean worktree of master, not in the working checkout: that
checkout carries unrelated uncommitted work, and zchecksums hashes files on
disk, so an -Update run there would have recorded hashes of files that are not
committed. Here the only inputs are what master holds.
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
* feat(zdeploy): -Scan / -s reports what is merged but not shipped, and deploys it
Port of the same feature in the internal toolkit. zdeploy.ps1 is hand-maintained
here - zpublish_zscripts refuses to copy it, because the private copy carries a
private product domain and project name - so this is a manual port rather than a
publish.
zdeploy -Scan report, then confirm
zdeploy -s -Yes unattended, no prompt
zdeploy -s <project> scan only these
It runs BEFORE the edge-first sort, so whatever it selects is still ordered by
that rule - the proxy ships before the apps behind it.
Every deploy already left .last_deploy_utc in the project's remote path; this
also writes .last_deploy_sha, which is the exact answer - deployed commit versus
current default-branch tip, independent of clocks. Projects that have not
deployed since fall back to comparing the tip's commit time against the deploy
time, marked "~" because it is approximate.
States: PENDING is selected; BLOCKED (uncommitted tracked files), no-stamp
(never deployed by a stamping zdeploy) and unknown (box did not answer) are
reported but never selected. A missing stamp says nothing about whether a
project is behind, so treating it as pending would deploy infrastructure on no
evidence.
Sanitization.Tests.ps1 caught a leak in the first version of this port - a
comment naming two private projects - and it is generalised here. That test is
why the manual-port rule exists.
CHECKSUMS.txt is deliberately NOT regenerated in this commit: zchecksums hashes
files on disk, and this checkout has unrelated uncommitted work (ZHelpers.ps1,
zstart.ps1 and others), so an updated manifest would record hashes of files that
are not committed. Run `zchecksums -Update` once that work lands.
Sanitization, ArgumentParsing and PlainTextTwins suites: 54 passed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(zdeploy): -Scan must not block on a redirected stdin
Read-Host throws under -NonInteractive - already caught - but with stdin merely
redirected (a pipe, a scheduled task, powershell.exe launched from another
shell) it blocks, waiting on a pipe that never answers. The first scan run that
way hung for ten minutes with its table already printed. The test is
[Console]::IsInputRedirected, checked before the prompt.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(zdeploy): stamp every deploy path, so -Scan can see edge, static and docker projects
Three of the six deploy paths - edge, static and docker - never wrote
.last_deploy_utc, so projects on those paths read no-stamp after every deploy
and the scan's remedy for that state did nothing when followed.
Get-RecordDeployBash now takes the zip name optionally (those paths upload no
zip) and each of the three stamps right before its Done line.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Build stamp catch-up for 1 merged PR(s) since v1.0.0.0.22:
135c585 docs(changelog): give every shipped release its own section, and generate the twin (#68)
The changelog said nothing had been released since 1.0.0. Twenty-two builds
had shipped. Twenty-one entries sat under "## Unreleased" in a file with
exactly two headings, so a reader at any tag found no section for the version
they were holding.
Which release carried which entry is DERIVED, not guessed: for every line in
the region, the commit that introduced it, then the earliest tag containing
that commit. That yields seven releases - .22, .21, .20, .19, .14, .8 and .0.
No entry text changed. A verification pass compares the multiset of
non-heading lines before and after and refuses to write if anything was lost,
gained or duplicated; entries move under their release, so it compares as a
multiset rather than in order.
CHANGELOG.txt was kept BY HAND and drifted the moment the .md was
reorganised, which is the failure the plain-text-twin rule exists to prevent.
readme_txt.py becomes plaintext_twins.py and renders every pair. It also
drops <!-- --> markers, invisible in markdown and stray punctuation in a text
file - that is the whole of README.txt's diff.
The --check that keeps twins honest was never run. readme_txt.py shipped one
and its docstring claimed "the test suite runs --check"; nothing invoked it,
so a twin could disagree with its markdown indefinitely.
tests/PlainTextTwins.Tests.ps1 runs it.
That test skipped on its first run while claiming to pass: -Skip is evaluated
during DISCOVERY, before BeforeAll, so the python lookup left the flag $null.
Resolved in BeforeDiscovery, and when python really is absent the result is
INCONCLUSIVE rather than a green tick for a check that never happened.
Mutation-checked: appending one line to CHANGELOG.txt fails "every twin is in
sync with its markdown", and only that test.
tests: 243 passed, 0 failed, 1 skipped (the no-python reporter, correctly).
Build stamp catch-up for 1 merged PR(s) since v1.0.0.0.21:
40fa250 refactor(tests): move the sanitization denylist to a data file both sides can read (#66)
The rules lived inside Sanitization.Tests.ps1, so the publisher in the
private toolkit kept its own second list -- and the two guarded different
things. The publisher's was about SECRETS: keys, private-key blocks, ssh
targets. These are about IDENTITY: internal project names, product domains,
private-only script names, operator paths.
So the publisher reported "clean" on files this suite rejects, and would
have published a tree that fails the public repo's own tests
(evo.scripts#106). Proven at the time by copying the private ZHelpers.ps1
in: two failures naming EvoCivilCode, EvoPlatform and three private-only
script names, against a scan that called the same file clean.
tests/sanitization-patterns.psd1 is now the one source. The suite reads it
and refuses to run if it is missing or empty, rather than passing vacuously
against no rules -- an empty denylist that reports success is the failure
this whole fix is about.
No rule changed. Only where they live.
.psd1 is not in the scanned extension list, which is deliberate and matches
why Sanitization.Tests.ps1 excludes itself: a file that necessarily contains
every pattern it looks for cannot also be scanned for them.
Pester: 240 passed, 0 failed. CHECKSUMS regenerated; changelog and its
plain-text twin updated.
The mirror's deploy pair had drifted ~280 lines behind: it lacked the
transactional .env preserve/restore (an interrupted deploy could destroy
server-side env files), the stderr-flattening step wrapper (a successful
deploy reported failure and skipped its own verification), and the
verification rework (channel re-picked every retry, edge only with a Host
to route by, verify.timeoutSeconds, honest split of "stale build" vs "no
channel answered").
The sync is byte-faithful to the private tree except where the mirror's
own Sanitization suite demands otherwise - and it caught the first copy:
three failures for private project names, a private domain, and a
private-only script name that rode along in comments. Each war story keeps
its lesson and loses its cast, per the convention already in the file
("EvoCivilCode: deploy/" was already published as "(deploy/, infra/,
...)"). That suite going red on an unsanitized copy is exactly what it
exists for.
Also in this change:
- tests/VerifyPlan.Tests.ps1 - the channel-selection rules are pure
functions and Pester pins them (no domain => no edge attempt; the PS 5.1
one-element-unroll trap). First verification tests in the mirror.
- README: the verify block now documents viaProxy/upstream (they shipped
in the docker-network read but were never in the README),
timeoutSeconds, and the channel order with why it re-resolves per retry.
- README.txt: generated plain-text twin, via scripts/readme_txt.py
(vendored from the fleet's reference implementation; the file is
generated, never edited by hand).
- CHANGELOG.md/.txt: entries merged into the existing Unreleased sections.
CHECKSUMS.txt refreshed (42 entries). Pester: 240 passed, 0 failed.
Both synced files parse clean.
Observed, untouched: the Unreleased section carries duplicate "### Fixed"
headings from earlier appends; folding them risks reordering entries whose
prose references their neighbours, so it is left for the next release cut
(zbump #110 rolls Unreleased into the version being cut).
zversion's usage block and its bump help line both said 'one per PR, one per
defect fix'. The build counter advances once per release: the number names
something that shipped, so a release carrying five PRs moves it by one, and
PRs that never shipped on their own were never separate builds.
This is help text rather than behaviour, but it is the wording that gets
followed - it is what stamped a single evo.www release as two builds. The
matching comments in ZHelpers.ps1 and zdeploy.ps1 are corrected with it.
CHECKSUMS.txt regenerated for the three edited scripts, since the manifest
tests fail the moment it drifts. CHANGELOG entry added under Unreleased, with
its .txt twin. The older CHANGELOG entry recording what the rule was when
zversion shipped is deliberately left as written - a changelog describes what
happened, not what is currently true.
Pester: 231 passed, 0 failed.
Build stamp catch-up for 1 merged PR(s) since v1.0.0.0.18:
e738b62 feat(version): read a live build from inside the docker network, not the public proxy (#59)
zdeploy, zec2 and zec2online now prefer
docker exec <viaProxy> curl http://<upstream>/api/build-version
when a project sets verify.viaProxy and verify.upstream.
Two problems it closes. A build stamp is something many sites deliberately
do not serve publicly, and a checker that reads it over the public URL stops
working the moment that endpoint is blocked -- reporting "unknown", which is
indistinguishable from "could not reach it". And the proxy answers from
whichever vhost matches the Host header, so a container with no public route
was getting another site's version back and failing deploys that had worked.
Reading it from a container on the shared network also exercises the real
HTTP path, so it proves the app is serving rather than that its database
knows a version. Purely additive: a project without those two keys behaves
exactly as before.
zec2 gains $PemKey and $SshTarget, which it had no need of until now -- the
read is inside a try/catch, so without them it would throw, be swallowed,
and fall through silently.
CHECKSUMS.txt regenerated (zchecksums -Update), zconfig.example.json
documents both shapes of the verify block, and CHANGELOG.md carries its
plain-text twin.
Pester: 231 passed, 0 failed -- including the sanitization suite.
Build stamp catch-up for 4 merged PR(s) since v1.0.0.0.14:
4230566 feat: two blank lines after every z-script run (#57)
432f210 fix(zdeploy): the pre-zip line states the label verification will require (#56)
fcbad44 feat(zdeploy): add the static deploy kind, and a test that keeps this repo sanitized (#55)
7b32bfa fix(zdeploy): docker kind now ships config subdirectories (#54)
zdeploy ended with two blank lines and nothing else did, so its output
was the only one that did not butt up against the next prompt. Applied
everywhere.
Implemented in Stop-ZTracking rather than per script, because every
tracked script ends by calling it - including the usage and guard paths
that do `Stop-ZTracking; exit 1`. One place therefore covers every exit
of sixteen scripts.
* Write-ZTrailer emits the two lines. Stop-ZTracking calls it on both
paths, including the early return when tracking never started - a
script that printed output still deserves the separation.
* -FinalNote prints one last line AFTER the tracking footer and BEFORE
the blanks. zdeploy's "Last deployed at ..." now goes through it, so
it stays the last thing on screen instead of being followed by the
token count.
* The standalone tools (zchecksums, zversion, zrelease) get a local
three-line copy at each exit rather than dot-sourcing ZHelpers -
they are deliberately dependency-free so they run from an extracted
release zip with nothing beside them.
* Redundant trailing blanks were removed where a script already
printed one before exiting, so the count is exactly two, not three.
Also fixes a related gap found while testing: the error exits inside
Get-ZConfig and Get-ZProject bypassed Stop-ZTracking entirely, so a run
that died on a missing zconfig.json printed no trailer AND no token
footer. Those three exits now route through Stop-ZTracking.
zkill/zrestart are one-line wrappers around scripts that already trail,
so they are untouched - adding it would double the blanks.
Verified by running each script and counting the trailing blank lines in
its captured output: 2 on every success path, every usage path, and the
config-error path. Suite 231/231. CHECKSUMS.txt refreshed.
Mirrors evo.scripts#79. Invoke-ViteDeploy announced "(server-side build will
bump +1)" and then Wait-VerifyStaticBuild asked for the committed stamp
unchanged, so the operator was told to expect one label and watched a check
pass on another.
The behavior was already correct; the message predates the removal of the
prebuild hook that used to self-bump inside the image. Wait-VerifyStaticBuild
documents it: "Expect the COMMITTED stamp, not +1: builds no longer
self-bump ... so 'is the build I just packed live?' means an exact match."
CHECKSUMS.txt regenerated, since zdeploy.ps1 changed.
Two things, both prompted by the same incident.
STATIC KIND
Plain static sites - no build, no container of their own; a shared web
container serves them off disk, so shipping the files IS the deploy.
Directories are staged to a sibling and swapped in with mv rather than
copied in place, because a large media file uploaded in place is served
half-written to anyone who requests it mid-copy. The swap is a rename,
so the switch is atomic.
Skips $JunkDirNames + .github + deploy.skipDirs, matching the docker
kind rather than inventing a third convention.
SANITIZATION TEST
This repo is public and must stay standalone, but the toolkit is
developed in a private checkout and copied here. Twice in three days a
wholesale copy landed carrying real project names, internal hostnames,
host disk figures, and references to scripts that exist only in the
private copy. Both times a human reading the diff caught it - the
control that fails exactly when a diff is 280 lines of good work with
three bad words buried in it.
So it is a test now. Seven rules: private project names, private product
domains, private-only script names, local drive paths, the operator home
path, the real key filename, and any IPv4 outside RFC 5737 documentation
space and the private ranges.
Two anti-vacuity guards, because a denylist that silently matches
nothing is worse than no denylist: one asserts the file scan is
non-empty, and one plants a known violation and requires the pattern to
find it.
The IP rule bounds on [\d.] rather than \d deliberately - this toolkit's
own 5-segment version (v1.0.0.0.14) contains "0.0.0.14", which a plain
digit boundary reads as an address.
Verified against the real unsanitized copy that slipped through: 3 of
the 7 rules fire, naming file and line.
Tests: 231/231 (222 + 9 new). CHECKSUMS.txt refreshed.
Invoke-DockerDeploy uploaded top-level files ONLY. For any stack that
keeps configuration in a directory, that is silently wrong in the worst
way: the compose file arrives, the containers restart, and the config
they read is whatever was already on the box. The deploy reports
success while shipping nothing that matters.
The sharp case is a provisioning directory read at container start -
alert rules, datasources, mounted config - where the restart makes it
look like the change was applied.
Same fix the edge kind already got: subdirectories ship recursively.
Skipped are $JunkDirNames, plus .github (CI config belongs in the repo,
never on a deploy target - it is not in $JunkDirNames because backups
DO want it), plus anything the project lists in the new
deploy.skipDirs.
deploy.skipDirs exists for SERVER-SIDE STATE that shares the tree: a
data/ holding mailboxes or a time-series database must never be
overwritten by whatever the local checkout has - usually nothing, which
is the dangerous case, since scp -r of an absent directory is not the
no-op you want to rely on.
CHECKSUMS.txt refreshed alongside. Tests: 222/222.
Build stamp catch-up for 3 merged PR(s) since v1.0.0.0.11:
6c30f40 feat(zdeploy): sync deploy hardening from the private toolkit (#53)
8959d9f fix(zdeploy): stop passing ssh -n to scp, which rejects it (#52)
d99f8a1 fix(zdeploy): stop mirroring the build stamp into the local checkout (#51)
Nine fixes that had accumulated only in the private copy. Each one is a
production failure that already happened:
* ssh -n on the deploy path. Without it ssh reads its stdin, inherits
the console handle under PowerShell, and can block forever. The
existing timeouts cannot catch it - they bound a connection that is
dying, and this one was never established. Get-Ec2ScpOpts derives
from the same list minus -n, because scp rejects it with a usage
error that reads like an unrelated failure.
* Invoke-DeployGitPull now switches TO the default branch instead of
pulling whatever is checked out. Pulling the current branch breaks
as soon as the remote deletes branches on merge, and worse, could
ship a feature branch to production. Refuses over local changes,
excluding the files the deploy itself stamps.
* nextjs handler resolves composeDir. It ran compose against
remote.path, so a project whose compose lives in a subdirectory
recycled whatever docker-compose.yml sat at the project root -
usually the local dev one shipped in the same archive. Two deploys
in a row exited 0 having shipped nothing, and verification passed
because the untouched old container still answered.
* BUILD BEFORE DOWN. The old order took the site offline for the whole
build and left it offline if the build failed - one deploy served
502 for 19 hours with no container running. The old image now keeps
serving until the new one is ready.
* compose build takes the named service, so a compose file that does
not define it fails loudly instead of succeeding with nothing to do.
* deploy.verifyHost overrides domain for verification only, for when a
domain is retired ahead of its replacement.
* deploy.stampCmd writes the build version from git before zipping,
then reverts the tree so the stamp cannot block the next deploy.
* Optional ztokens pseudo-project and passive usage records. Both
degrade to a printed skip when no sibling ztokens checkout exists.
Sanitized on the way across, per the public-repo rule: the war stories
that make these comments worth reading are kept, the private product
names, domains, internal script names, outage dates and host figures are
not. Also dropped a "See issue #28" pointer that resolves to an
unrelated PR in this repo, and two references to scripts that exist only
in the private toolkit.
CHECKSUMS.txt refreshed alongside, per the manifest rule.
Tests: 222/222 (the 4 failures before the refresh were the checksum
suite correctly flagging both edited files).
Mirrors evo.scripts #66, which added -n to Get-Ec2SshOpts so a deploy step
cannot block on inherited stdin, plus the follow-up that keeps that flag away
from scp. OpenSSH's scp has no -n: it exits 1 with 'unknown option -- n' and
prints its usage block, so every upload failed once the shared option array
reached it.
Get-Ec2ScpOpts is derived from Get-Ec2SshOpts with -n filtered out rather than
duplicated, so the connect and keepalive timeouts cannot drift apart between
the two transports. All four scp call sites here use it - three plain uploads
and the recursive directory upload, which the private tree does not have.
The upload failure message asserted 'Likely server disk space' without checking
anything; it now points at scp's own output, where the real diagnosis already
was.
Verified: both files parse clean, Get-Ec2ScpOpts returns the five -o pairs with
no -n, and the added lines carry no real hosts, keys, or paths.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Mirrors evomedia-net/evo.scripts#62. Every python-kind deploy wrote
build-version.json locally, leaving the tree dirty; committing it hit
branch protection, so a deploy either tripped the next deploy's
clean-tree guard or bypassed the rule.
The build number is bumped in the container, written to .build_version
on the server, and proven by /api/build-version. The repo file records
the stage baseline only.
Build stamp catch-up for 1 merged PR(s) since v1.0.0.0.10:
a1dd642 chore(changelog): drop the product name from the versioning entry; add the plain-text twin (#50)
'the SmartPlant 5-segment scheme' was the only product-name reference
left anywhere in the public tree (found by a full sanitization sweep:
paths, keys, domains, IPs, emails, ssh details, sibling-repo coupling
- everything else already clean). The scheme description stands on its
own without naming where it came from.
CHANGELOG.txt is the plain-text mirror the docs rule requires for any
touched .md - generated mechanically (headings underlined, markup
stripped, code blocks indented).
CHECKSUMS.txt is untouched: it covers .ps1/.cmd only.
With deploy.gitPull set, Invoke-DeployGitPull ran `git pull --ff-only`.
Pull merges whatever .git/FETCH_HEAD marks "for merge", and a
concurrent fetch in the same repo - an editor's background auto-fetch
racing the deploy - can leave duplicate for-merge lines. Pull then dies
with "Cannot fast-forward to multiple branches" even when both lines
name the same commit. Reproduced live on 2026-08-13: the deploy failed
at step 0, and by inspection time the same pull succeeded, with the
duplicated FETCH_HEAD entries as the only evidence.
Now the function fetches explicitly and fast-forwards against the
remote-tracking ref:
git fetch origin
git merge --ff-only origin/$branch
Identical fast-forward-or-refuse semantics, but nothing shared and
mutable in the path. A failed fetch and a failed merge now also throw
distinct messages, so the operator knows which half broke.
CHECKSUMS.txt refreshed alongside, per the manifest rule.
Tested: PS 5.1 parse clean; full Pester suite 222/222 after the
manifest refresh (the 3 pre-refresh failures were the checksum suite
correctly flagging the edited file). The same fix pattern was
exercised against live and scratch repos for the private twin
(evomedia-net/evo.scripts#58): behind -> fast-forwards, diverged ->
refuses and aborts the deploy.
Closes#48
tests/Invoke-Coverage.ps1 runs the suite with Pester's profiler-based
coverage collector and writes both JaCoCo XML and a coverage-summary.json
in the same shape vitest and jest emit, so one reader handles every tool
in the fleet.
CodeCoverage.Path is every *.ps1 in the repo root, including the ones no
test touches. They report 0% and drag the total down, which is correct -
measuring only the already-tested files answers "how well covered is the
covered code". The same mistake in vitest form had evo.www reporting 93%.
Baseline: 222 tests pass, 7.0% of commands (219/3,125 across 24 scripts).
Pester counts commands, not statements; the collector labels it as such
rather than filing it under a unit it is not.
Build stamp catch-up for 8 merged PR(s) since v1.0.0.0.0:
6c03138 fix(zdeploy): deploy edge first for any project list, not just 'all' (#46)
976eb6d chore: point repo URLs at evomedia-net/evo.* (#44)
0e4d9c3 fix(zdeploy): ship edge asset subdirectories, stop deploys hanging on ssh prompts, keep vendored archives (#43)
c8fcfee fix(zdeploy): verify Next.js deploys on the server instead of probing the public IP (stops the bogus security-group warning) (#41)
b84d24b fix(zdeploy): report where a domain-less project deployed to (#40)
4668404 fix(zdeploy): re-land the two blank lines after the timestamp (#38)
a868973 fix(zdeploy): verify against the committed build stamp, and read 5-segment versions (#37)
0ddffc1 feat(zdeploy): print 'Last deployed at' timestamp as the last line of a run (#36)
