Five PRs (#11, #23, #10, #12, #24) landed on master since this branch opened.
Conflicts were all additive and in the same spots this PR documents its new
'install' key: README's config reference and both zconfig.example.json files,
where #12 had added the startApp note on the adjacent line. Resolved by keeping
both keys, with the startApp note next to startModule (it documents that key)
and install after it. Nothing dropped from either side.
* feat(zec2_rotatekeys): rotate/reset server-side secrets without exposing values
New tool for the leaked/overwritten prod .env case: -Rotate KEY regenerates a
key ON THE SERVER (openssl rand -hex 32) so the value never leaves the box;
-Set KEY takes an operator-known value from a masked prompt and streams it over
SSH stdin (never a command arg, never echoed). Backs the server .env up to a
timestamped .bak first, updates keys atomically (match-or-append), auto-detects
backend/.env from deploy.preserve, restarts only with -Restart, and -WhatIf
previews the plan. Docs added to README + CHANGELOG.
* fix(zec2_rotatekeys): recreate container on -Restart so the new .env loads
A plain 'docker compose restart' reuses the container's existing environment
and would NOT pick up env_file changes, leaving the app on the old secrets
after a rotation. -Restart now runs 'up -d --force-recreate <svc>', the
reliable way to apply the new .env. Docs updated to match.
* feat(zstart): support uvicorn/ASGI apps via a startApp config field
Python projects could only be started as `python -m <startModule>`, so
FastAPI/ASGI apps that run under uvicorn (like evo-ai:
`uvicorn app.main:app`) couldn't be started by zstart in either port.
Add an optional `startApp` field. When set, zstart runs
`uvicorn <startApp> --host <bind-host> --port <ports.dev> --reload` via
the venv python's -m (no PATH juggling), integrating zstart's existing
bind-host and dev-port handling. startApp takes precedence over
startModule; a python project still needs one or the other. Applied to
bash and PowerShell, documented in the README + example configs.
* feat(zstart): warn when falling back to system python (no project venv)
A python project with no .venv (or only a Windows .venv when on WSL)
silently ran under the system interpreter, which usually lacks the
project's deps - producing a cryptic ModuleNotFoundError far from the
cause. Now zstart prints a clear warning naming the missing venv and the
one-liner to create it, before starting. Bash + PowerShell.
* fix(bash): zstart --detached no longer hangs on the tracking FIFO
Detached mode forked the long-lived server while it still inherited the
ztokens tracking fds (the capture FIFO on 1/2, saved stdout/stderr on
3/4). The parent's EXIT-trap footer runs `tee` on that FIFO and waits for
EOF, which never came while the server held it open - so `zstart
--detached` (and zstartd / zrestart --detached) hung instead of
returning. detach() now redirects stdin<-/dev/null, stdout/stderr->log
and closes fd 3/4 before exec'ing the server. Verified on WSL: detached
returns in 0s and the server still boots.
* fix(zstart): git-pull pre-step can't hang on a credential prompt
start.gitPull ran `git pull --ff-only` before starting the server; in an
environment with no cached git credentials (e.g. WSL against an HTTPS
GitHub remote) git prompted "Username for 'https://github.com':" and the
whole start blocked on stdin. Run the pull with GIT_TERMINAL_PROMPT=0 so
it fails fast, log a clear "auto-pull skipped" note, and start with the
current checkout. Bash + PowerShell.
* fix(ps): zbackup explicit target + robust DATABASE_URL parsing; ssh-stderr deploy fix
Restores parked, previously-uncommitted PowerShell improvements:
- zbackup / zbackup_and_sync require an explicit target: bare invocation
now prints usage instead of quietly backing up everything; 'all' does
what bare used to (matching zdeploy). setup_backup_schedule.ps1 passes
'all' to the scheduled task; both tolerate switch-style args.
- zbackup parses more DATABASE_URL styles: strips surrounding quotes
(Prisma convention), accepts postgres:// and postgresql+driver://
schemes, and treats the port as optional (defaults to 5432).
- Invoke-Ec2Step survives ssh stderr warnings: under ErrorActionPreference
'Stop', PS 5.1 turns any native stderr line (e.g. Docker's COMPOSE_BAKE
deprecation notice) into a terminating NativeCommandError, aborting a
deploy that actually succeeded. Drop to Continue locally and flatten
stderr so only the real exit code decides success.
* fix(ps): zbackup reports the real pg_dump failure, not "No DATABASE_URL"
Mirror of the bash fix. Invoke-LocalPgDump now owns all its messaging
(caller just captures success) and distinguishes the cases:
- no .env / no DATABASE_URL -> calm "No local DATABASE_URL".
- database not reachable (connection refused / could not connect / DNS /
timeout) -> calm "Local database not running at host:port" - a stopped
dev DB is a normal state.
- any other failure (version mismatch, auth, missing db) -> the loud,
full pg_dump error plus the host:port/db it tried, instead of a bare
"pg_dump failed (exit N)" followed by a misleading "No DATABASE_URL".
Captures pg_dump stderr (was 2>$null); drops ErrorActionPreference to
Continue locally so PS 5.1 doesn't turn that stderr into a terminating
NativeCommandError under the script's 'Stop' setting.
Only nextjs-kind excluded .env* from the deploy archive; python and vite
did not - so a project's local .env at its root got zipped and shipped to
the server on every deploy, planting local secrets over the server's own
(the operator-file restore only wins for files it preserved). Add
.env/.env.local/.env.production to the python and vite deploy excludes,
matching nextjs. Kept DEPLOY-only (like `uploads`): backups still capture
.env so a source backup stays complete. Bash + PowerShell.
Note: this covers a ROOT .env. A nested secret (e.g. DocketMail's
backend/.env) is handled separately via deploy.preserve in the project's
zconfig.
These three defaulted to "every project" when run with no arguments -
inconsistent with zbackup/zdeploy/zstart/etc. (which show usage), and a
surprising amount of work to kick off by accident: zbackup_ec2 pulls a
server backup of every project, and zec2online deep-checks everything AND
auto-starts any downed stacks. Now a bare invocation prints usage and
lists the projects; 'all' does what bare used to. Applied to both the
bash and PowerShell versions.
* fix(bash): zbackup reports the real pg_dump failure, not "No DATABASE_URL"
local_pg_dump returned 1 for four different cases (no .env, no
DATABASE_URL, unparseable URL, and an actual dump failure), and the
caller printed "No local DATABASE_URL - source-only backup" for every
one. So a project that HAS a DATABASE_URL whose dump failed was
mislabeled as having none — the two messages contradicted each other.
- Distinguish the cases with exit codes: 0 dumped, 1 attempted-but-failed,
2 no local database. The caller now prints the right line for each.
- Stop swallowing pg_dump's stderr (2>/dev/null); on failure, surface the
actual error (version mismatch, unreachable host, auth) plus the
host:port/db it tried, so failures are diagnosable.
* fix(bash): zbackup treats a not-running local DB as a calm skip
Fold all pg_dump messaging into local_pg_dump (caller just captures
success) and special-case an unreachable database. "connection refused"
/ "could not connect" / DNS / timeout now print a quiet
"Local database not running at host:port - source-only backup." instead
of a red multi-line error - a stopped dev DB is a normal state. Real
failures (version mismatch, auth, missing db) still print the full
pg_dump error so they're diagnosable.
* fix(bash): zbackup/zbackup_and_sync require an explicit target, matching PowerShell
Bare `zbackup` quietly backed up every project - inconsistent with the
PowerShell version (and with zdeploy), and an easy way to kick off a
huge unintended backup. Now a bare invocation prints usage and lists the
projects; `all` does what bare used to (every project + the scripts
folder). Same for `zbackup_and_sync`, and setup_backup_schedule's cron
line now passes `all` so the scheduled job still backs everything up.
zkill now accepts 'all', expanding to every project that has a ports.dev
(edge/docker stacks with no local dev server are skipped) - matching
zdeploy all / zbackup all. Ported to both the PowerShell (ZKillOnly.ps1)
and bash (bash/zkill) versions; README + CHANGELOG updated.
zstart only warns when a python project has no venv; zsetup is the
command that provisions one. For a python project it creates <root>/.venv
and installs deps; for vite/nextjs it runs npm install. Idempotent.
The pip install command comes from the project's optional "install"
config field (e.g. "-e backend" for deps in a subfolder, "-r reqs.txt"),
or is auto-detected from a root pyproject.toml/setup.py ("-e .") or
requirements.txt ("-r requirements.txt"). Bash + PowerShell + .cmd
wrapper, documented in the README and example configs.
The README advertises macOS support, but the port used constructs that
fail on the userland macOS actually ships:
- `mapfile` (bash 4+) in 10 spots — macOS ships bash 3.2 as /usr/bin/bash,
so a mac user following the README hit "mapfile: command not found" and
silently got empty project lists. Replace each with a portable
`while IFS= read -r` loop (identical arrays; set -u safe on empty input).
- `_z_commafy` used the GNU-only `sed :a;...;ta` label/branch idiom, which
errors on BSD/macOS sed (the token footer's thousands separators).
Reimplement with awk (already a dependency).
- README: correct the macOS line — bash 4+ does NOT ship with macOS; the
stock 3.2 now works, and only jq needs brew.
Also two correctness nits found in the same review:
- zkill/zrestart `--kill-all` was parsed but silently ignored; now it
prints a "not implemented in the bash port" notice instead of no-op.
- zrepair's smoke-test line said "https://$domain" but probes
http://$HOST with a Host header; label now matches what it does.
Verified on WSL (bash 5): read-loops produce the same 11 project / 7
domain keys as mapfile; awk commafy matches across 0..1,234,567; empty
producer yields a 0-length array; footer renders. 3.2-compat is by static
analysis — no bash-4-only constructs remain.
* fix(bash): translate Windows config paths to WSL/Unix form
A shared zconfig.json (one file used from a Windows checkout and from
WSL via the symlink) holds Windows paths like "F:\evomedia.net\app".
The bash port passed those to local file ops verbatim, so every
path-using command failed on WSL (e.g. zbackup: "Root not found:
F:\evomedia.net\evomedia-docs").
Add a z_path helper that converts drive-letter paths to the host's
native form (wslpath, with a /mnt fallback) and is a no-op for Unix
paths and empty strings — so a bash-native config is unaffected. Route
every LOCAL path through it: localRoot (new zproj_root accessor),
paths.* (temp, backupsLocal, backupsEc2, scriptsRoot, oneDriveBackups),
ec2.pemKey (zec2_pem), and ztokens.dataDir. Server-side paths
(remote.path, composeDir, stackRoot, certsSource) are left verbatim.
Verified on WSL: all 11 project roots, all paths.*, and the C:/G: pem
and OneDrive paths resolve to existing dirs; zbackup evodocs (the
failing case) now runs clean end-to-end.
* fix(bash): keep z_path fallback bash-3.2 clean (tr, not ${x,,})
The wslpath-absent fallback lowercased the drive letter with ${drive,,},
a bash-4.0 construct that breaks on macOS's stock bash 3.2. Use tr
instead so the whole helper stays 3.2-compatible.
* feat(bash): native bash port of all z-scripts for Linux/macOS/WSL
Full port: zhelpers.sh library (jq config, ssh, http/tcp, archive builder,
build-version, motd, port-kill), all commands (zstart/zkill/zrestart/zstop,
zdeploy with 5 kind handlers, zec2/zec2online/zrepair, zbackup/zbackup_ec2/
zsync/zbackup_and_sync, zstart_docker, zsetup_mail, setup_backup_schedule via
cron), Unix-path zconfig.example.json, and a bash/README.md.
Verified: bash -n clean on all scripts; archive exclusions, config semantics,
and zec2 tested against the real config and live server from Git Bash. Needs a
Linux/macOS/WSL shakedown for lsof/rsync/nohup paths before merging.
* chore: pin line endings (.gitattributes) - bash LF, powershell CRLF
* docs(readme): point Linux/macOS/WSL users at the bash port
* fix(bash): don't run the Windows venv python.exe on WSL/Linux/macOS
zstart's venv detection fell back to .venv/Scripts/python.exe (a Windows
binary) whenever it existed. On a Windows-built project accessed from WSL that
file sits on the mount and looks executable, so it got picked and failed with
'exec format error' instead of falling through to python3. Guard that branch to
Windows-family shells (msys/cygwin), where a .exe can actually run.
Verified on WSL: zstart --detached now backgrounds a stdlib app via python3,
serves HTTP 200, logs to /tmp/zstart-<key>.log, and zkill terminates it and
frees the port.
* feat(bash): add token-usage tracking to the bash port (#6)
Adds z_track_start/z_track_stop + z_record to zhelpers.sh and wires
z_track_start into every command script. Each run now captures its own output
volume (FIFO+tee, ANSI stripped), prints the '--- N lines / N chars / ~N tokens
est. (Claude Code) ---' footer, and appends one JSONL row per top-level run in
the same shape as the PowerShell tokens.jsonl. A nested-run guard keeps
zrestart from double-counting its zkill/zstart children.
Data dir precedence: $ZTOKENS_DATA, config ztokens.dataDir, sibling
../../ztokens/data, else ~/.ztokens/data. Docs + example config updated.
Verified on WSL (isolated data dir): single run records correctly; nested
zrestart produces one combined record, not three; est = round(chars/3.5).
The project-directory replacement preserved only ./.env, silently
destroying every other server-side file (.env.db, staged signing keys,
certs) on every deploy — and the vite kind preserved nothing at all.
- preserve all .env* files at the project root by default
- new deploy.preserve array for additional files/directories
- implemented via tar to the home dir before the wipe, extract after
the unzip; server-side copies win over zip contents (same semantics
./.env always had)
- helpers deliberately avoid embedded quotes and $( ): PowerShell 5.1
strips embedded double quotes when passing args to ssh.exe, which
silently corrupts remote commands (discovered when v1 of this fix
failed exactly that way)
Fixes#2
Projects not published through the edge proxy had a false-PASS problem:
the fallback reachability check hit http://<server-ip>/, which the
proxy's default vhost happily answers for apps that never started.
- new Test-DeployHealth: checks the app FROM the server over SSH
(curl localhost:<port><path>), optional expected substring
- opt in per project: "verify": { "port", "path", "expect" }
- projects with neither domain nor verify are reported NOT verified
instead of green-lighting the proxy's default page
- example config + README + changelog updated
Per-run captures are measured; the ~26,500/day total multiplies them by assumed
typical run counts (zdeploy/zrestart at 10-15/day dominate). Label that boundary
explicitly in README, ELEVATOR_PITCH, and TOKEN_SAVINGS so the daily figure isn't
read as a direct measurement.
- One headline number everywhere: ~26,500 measured tokens/day (README said 3,000-7,000; ELEVATOR_PITCH said 157,000-540,000)
- Measurement note: measured output volume, estimated tokenization; /3.5 is conservative for code-heavy output
- Raw-orchestration column explicitly labeled an upper bound, not a prediction
- Measured dollar column priced at input rates (blended kept for est-raw only); note on re-sent context tokens
- Untrack md/Z-ScriptTokenData.md (superseded internal notes; md/ gitignored)
Config-driven PowerShell scripts to run infrastructure tasks (deploy, restart, backup, diagnostics) yourself instead of having an AI agent orchestrate them, to save agent tokens. Environment specifics live in zconfig.json (gitignored).
