From 76e1e78c55d322bede883caa402268f1329d5e5e Mon Sep 17 00:00:00 2001 From: ZDDC Date: Sat, 2 May 2026 08:29:58 -0500 Subject: [PATCH] chore: ./build is dev-only; ./build alpha is the explicit deploy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reverts the prior CLI simplification. ./build (no arg) now does source work only — tool dist/ + cross-compiled zddc-server binaries — and leaves the website worktree alone. Channel/release cuts are explicit: ./build dev build (source only, no deploy) ./build alpha cut alpha (cascades nothing) ./build beta cut beta (cascades alpha → beta) ./build release [X.Y.Z] cut stable (cascades all) Rationale: editing source shouldn't have a side-effect on the live site. The website worktree at ~/src/zddc-website/ is what Caddy serves in real time, so any write to it is a deploy. Treating dev iteration as alpha-publish was confusing — the user wanted source builds and deploys to be distinct verbs. Mechanically: a `dev` (default) branch is added to the case statement; the post-build matrix-index regen + channel-link verifier are conditional on RELEASE_CHANNEL being set; dev builds skip them. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 29 +++-- CLAUDE.md | 18 ++- build | 127 +++++++++++-------- mdedit/dist/mdedit.html | 2 +- zddc/internal/apps/embedded/archive.html | 2 +- zddc/internal/apps/embedded/classifier.html | 2 +- zddc/internal/apps/embedded/index.html | 2 +- zddc/internal/apps/embedded/mdedit.html | 2 +- zddc/internal/apps/embedded/transmittal.html | 2 +- zddc/internal/apps/embedded/versions.txt | 10 +- 10 files changed, 112 insertions(+), 84 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4fea8ce..9147894 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,25 +3,26 @@ ## Commands ```bash -# ── Lockstep release driver: every invocation is a publish action. ──────── -# Alpha is the default since "alpha = active dev iteration" and that's -# what running the build IS. Coordinated version (for release): max -# across all six tools' latest tags + 1. Workflow: -# alpha = active dev → beta = ready for general testing → stable = ship +# ── ./build subcommands ──────────────────────────────────────────────────── +# `./build` (no arg) is a source-side dev build only — assembles tool/dist/ +# + cross-compiles zddc-server. The website worktree is left alone. +# Channel + release subcommands deploy artifacts to the website worktree +# under $ZDDC_DEPLOY_RELEASES_DIR (default ~/src/zddc-website/releases). +# Workflow: alpha = active dev → beta = ready for testing → release = ship. -./build # cut alpha (default) — cascades nothing -./build beta # cut beta — cascades alpha → beta -./build release # cut stable — coordinated next version, - # cascades all to the new version +./build # dev build (no website worktree write) +./build alpha # cut alpha (cascades nothing) +./build beta # cut beta (cascades alpha → beta) +./build release # cut stable, coordinated next version + # (cascades alpha + beta → new stable; tags all six) ./build release 1.2.0 # cut stable at explicit version -./build help # usage +./build help -# Build a single HTML tool's dist/ for testing (does NOT touch the -# website worktree's release artifacts): +# Single-tool dev build for testing (does NOT touch the website worktree): sh tool/build.sh # archive|transmittal|classifier|mdedit|landing -# Single-tool release (rare; prefer the lockstep ./build above so -# versions don't drift between tools). Same flag form as before. +# Single-tool release (rare; prefer ./build alpha|beta|release so versions +# don't drift between tools). Same flag form as before. sh tool/build.sh --release [|alpha|beta] ./freshen-channel # rebuild one tool's alpha/beta from its current stable tag diff --git a/CLAUDE.md b/CLAUDE.md index 25af705..2c8db5d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,15 +25,19 @@ This is a **monorepo of independent tools**, not one application: ## Most-used commands ```bash -# Lockstep release driver. Every invocation is a publish action; -# alpha is the default since "alpha = active dev iteration". -./build # cut alpha (default) -./build beta # cut beta — cascades alpha → beta -./build release # cut stable — coordinated next version, cascades all +# Source-side dev build only — assembles tool/dist/ + cross-compiles +# zddc-server. Does NOT write to the website worktree. +./build + +# Channel/release cuts — write into ~/src/zddc-website/releases/ +./build alpha # cut alpha (cascades nothing) +./build beta # cut beta (cascades alpha → beta) +./build release # cut stable, coordinated next version + # (cascades alpha + beta → new stable; tags all six tools) ./build release X.Y.Z # cut stable at explicit version ./build help # usage -sh tool/build.sh # build one HTML tool's dist/ (no channel write) +sh tool/build.sh # iterate on one HTML tool's dist/ sh tool/build.sh --release [...] # single-tool release (rare; prefer the lockstep ./build) ./freshen-channel # rebuild one tool's alpha/beta from its current stable tag @@ -55,7 +59,7 @@ No lint/typecheck/format commands exist for the HTML tools — vanilla JS + POSI - **No tags for alpha/beta.** Channel URLs are stable URLs by design — appending counter tags would defeat the purpose. The on-page label encodes ` · ` for traceability. Stable cuts get clean `-vX.Y.Z` tags for every tool (six tags per cut, all sharing the same X.Y.Z). - **Pre-release semver in the on-page label.** Plain dev builds and `--release alpha|beta` cuts embed `vX.Y.Z-{alpha,beta}` in `{{BUILD_LABEL}}` where X.Y.Z is the next-stable target. Plain dev adds a full timestamp + `-dirty` marker; `--release alpha|beta` is date-only. - **Channel-link verifier.** Every `./build` ends with a check that every `_{stable,beta,alpha}.html` (and zddc-server's per-platform binary mirrors + stub pages) resolves. Bootstrap-friendly: skips zddc-server checks until the first `--release` cut materializes the binaries. -- **`sh tool/build.sh` is a single-tool dev build.** Writes `dist/.html` only; no new per-version files / symlink updates in the website worktree. Useful for iterating on one tool without cutting alpha for the whole suite. To publish, run `./build` (cuts alpha for everything together). Release artifacts always land in `${ZDDC_DEPLOY_RELEASES_DIR:-~/src/zddc-website/releases}`; nothing is pushed automatically — commit + push the website branch when you want to publish. +- **`./build` (no arg) is a source-side dev build.** Assembles `tool/dist/` + cross-compiled binaries; does NOT write to the website worktree. Use it to iterate without affecting the live site. To deploy, run `./build alpha|beta|release` — those promote to `${ZDDC_DEPLOY_RELEASES_DIR:-~/src/zddc-website/releases}`. Nothing is pushed to Codeberg automatically; commit + push the website branch when you want to publish. - **Always build before running tests** — Playwright opens `dist/tool.html` via `file://`. - **``** embedding. `shared/build-lib.sh` provides `escape_js_close_tags`; every tool's `build.sh` runs JS through it before inlining. - **All ZDDC parsing/formatting/hashing goes through `window.zddc`** (from `shared/zddc.js` + `shared/hash.js` + `shared/zddc-filter.js`). API: `parseFilename`, `parseFolder`, `parseRevision`, `formatFilename`, `formatFolder`, `compareRevisions`, `isValidStatus`, `splitExtension`, `joinExtension`, `crypto.{sha256Hex, sha256String, sha256File, bytesToHex}`, `filter.{parse, matches}`. File objects across tools use `trackingNumber` (string) and `extension` (string, **no leading dot** — use `zddc.joinExtension(name, ext)` to build a filename). Add edge cases to `tests/zddc.spec.js`, not per-tool tests. diff --git a/build b/build index f062684..6b8233c 100755 --- a/build +++ b/build @@ -1,27 +1,26 @@ #!/bin/sh set -eu -# build — lockstep release driver for ZDDC. +# build — ZDDC source build + lockstep release driver. # -# Three subcommands. The first arg names a channel and every invocation -# is a publish action — alpha is the default since "alpha = active dev -# iteration" and that's what running the build IS. +# ./build dev build: assemble tool dist/, cross-compile +# zddc-server binaries. NO write to the website +# worktree; nothing gets deployed. +# ./build alpha dev build + copy alpha mirrors to the website +# worktree (cascades nothing). +# ./build beta dev build + copy beta mirrors (cascades alpha → beta). +# ./build release dev build + cut coordinated stable +# (cascades alpha + beta → new stable; tags all six tools). +# ./build release X.Y.Z same, explicit version. +# ./build help this message. # -# ./build cut alpha (default; active dev iteration) -# ./build beta cut beta (cascades alpha → beta) -# ./build release cut stable (coordinated next version; -# cascades alpha + beta → stable) -# ./build release X.Y.Z cut stable at explicit version -# ./build help this message +# Lockstep: every channel/release cut bumps all six tools (5 HTML + +# zddc-server) together. Coordinated next-stable = max(latest tag) + 1. # -# Lockstep: every cut bumps all six tools (5 HTML + zddc-server) -# together. The coordinated next-stable version is -# max(latest tag across all tools) + 1. -# -# Output goes to ${ZDDC_DEPLOY_RELEASES_DIR:-$HOME/src/zddc-website/releases} -# — the website branch's worktree, which is what Caddy serves. Nothing -# is pushed automatically; commit + push the website branch yourself -# when you want the changes mirrored to Codeberg. +# Channel/release cuts write to the website worktree at +# ${ZDDC_DEPLOY_RELEASES_DIR:-$HOME/src/zddc-website/releases}. Caddy serves +# that path live; nothing is pushed to Codeberg automatically. To publish: +# cd ~/src/zddc-website && git add -A && git commit && git push origin website SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd) @@ -33,10 +32,17 @@ root_dir="$SCRIPT_DIR" . "$SCRIPT_DIR/shared/build-lib.sh" # --- Parse subcommand ------------------------------------------------------ +# RELEASE_CHANNEL empty means dev mode (build only, no website worktree +# writes); set means a channel/release cut that promotes to the website +# worktree under $ZDDC_DEPLOY_RELEASES_DIR. RELEASE_CHANNEL="" RELEASE_VERSION="" -case "${1:-alpha}" in +case "${1:-dev}" in + dev|build) + # Dev build: tool dist/ + zddc-server binaries only. Touches + # nothing in the website worktree. + ;; alpha) RELEASE_CHANNEL="alpha" ;; @@ -64,9 +70,11 @@ case "${1:-alpha}" in ;; esac -# Per-tool argument list. The single-tool build.sh scripts still take -# the legacy `--release [channel|version]` form, so translate. -if [ "$RELEASE_CHANNEL" = "stable" ]; then +# Per-tool argument list. Pass --release flag only when we're cutting +# a channel/release; dev builds invoke each tool with no args. +if [ -z "$RELEASE_CHANNEL" ]; then + TOOL_RELEASE_ARGS="" +elif [ "$RELEASE_CHANNEL" = "stable" ]; then TOOL_RELEASE_ARGS="--release $RELEASE_VERSION" else TOOL_RELEASE_ARGS="--release $RELEASE_CHANNEL" @@ -218,13 +226,16 @@ echo " binary version: $ZDDC_BINARY_VERSION" ' # --- Promote zddc-server release artifacts --------------------------------- -# Copy the freshly cross-compiled binaries to the website worktree's -# releases/ under their canonical names + symlinks. promote_zddc_server -# also re-runs write_zddc_server_stubs_all internally, so the matrix-cell -# stub pages get regenerated in the same call. -echo "" -echo "=== Promoting zddc-server $RELEASE_CHANNEL release ===" -promote_zddc_server "$RELEASE_CHANNEL" "$RELEASE_VERSION" "$RELEASES_DIR" "$SCRIPT_DIR/zddc/dist" +# On a channel/release cut, copy the freshly cross-compiled binaries to +# the website worktree's releases/ under their canonical names + +# symlinks. promote_zddc_server also re-runs write_zddc_server_stubs_all +# internally, so the matrix-cell stub pages get regenerated in the same +# call. On a plain dev build, skip — we don't touch the worktree. +if [ -n "$RELEASE_CHANNEL" ]; then + echo "" + echo "=== Promoting zddc-server $RELEASE_CHANNEL release ===" + promote_zddc_server "$RELEASE_CHANNEL" "$RELEASE_VERSION" "$RELEASES_DIR" "$SCRIPT_DIR/zddc/dist" +fi # Latest stable version, by following archive_stable.html → versioned target. # Returns "" if no stable cut exists yet (bootstrap state). All HTML tools @@ -623,29 +634,41 @@ PIN_END echo "Wrote $_out" } -echo "" -echo "=== Building releases/index.html ===" -build_releases_index - -echo "" -echo "=== Verifying channel links ===" -verify_channel_links "$RELEASES_DIR" - -echo "" -echo "=== All tools built successfully ===" -echo "" -echo "Cut: $RELEASE_CHANNEL" -if [ -n "$RELEASE_VERSION" ]; then - echo "Version: v$RELEASE_VERSION" +# Matrix index + verifier only run when we touched the website +# worktree. Dev builds leave the worktree alone. +if [ -n "$RELEASE_CHANNEL" ]; then echo "" - echo "Tags created locally on main (push when ready):" - for _t in archive transmittal classifier mdedit landing zddc-server; do - echo " ${_t}-v${RELEASE_VERSION}" - done - echo " git push origin main && git push origin --tags" + echo "=== Building releases/index.html ===" + build_releases_index + + echo "" + echo "=== Verifying channel links ===" + verify_channel_links "$RELEASES_DIR" fi + echo "" -echo "Artifacts written to $RELEASES_DIR/" -echo " cd $(dirname "$RELEASES_DIR") && git status # to review the deploy" -echo " cd $(dirname "$RELEASES_DIR") && git add -A && git commit && git push origin website" -echo " ↑ commits + pushes the website branch when you're ready to publish" +echo "=== Build done ===" +echo "" +if [ -z "$RELEASE_CHANNEL" ]; then + echo "Mode: dev (source-only build, website worktree untouched)" + echo " tool/dist/*.html ready" + echo " zddc/dist/zddc-server-* binaries ready" + echo "" + echo "To deploy alpha mirrors to the website: ./build alpha" +else + echo "Cut: $RELEASE_CHANNEL" + if [ -n "$RELEASE_VERSION" ]; then + echo "Version: v$RELEASE_VERSION" + echo "" + echo "Tags created locally on main (push when ready):" + for _t in archive transmittal classifier mdedit landing zddc-server; do + echo " ${_t}-v${RELEASE_VERSION}" + done + echo " git push origin main && git push origin --tags" + fi + echo "" + echo "Artifacts written to $RELEASES_DIR/" + echo " cd $(dirname "$RELEASES_DIR") && git status # to review the deploy" + echo " cd $(dirname "$RELEASES_DIR") && git add -A && git commit && git push origin website" + echo " ↑ commits + pushes the website branch when you're ready to publish" +fi diff --git a/mdedit/dist/mdedit.html b/mdedit/dist/mdedit.html index 637cfb8..40affdc 100644 --- a/mdedit/dist/mdedit.html +++ b/mdedit/dist/mdedit.html @@ -1774,7 +1774,7 @@ body.help-open .app-header {
ZDDC Markdown - v0.0.9-alpha · 2026-05-02 · 76820fa + v0.0.9-alpha · 2026-05-02 · 6167e99
diff --git a/zddc/internal/apps/embedded/archive.html b/zddc/internal/apps/embedded/archive.html index 161cc96..7e276f5 100644 --- a/zddc/internal/apps/embedded/archive.html +++ b/zddc/internal/apps/embedded/archive.html @@ -2113,7 +2113,7 @@ td[data-field="trackingNumber"] {
ZDDC Archive - v0.0.9-alpha · 2026-05-02 · 76820fa + v0.0.9-alpha · 2026-05-02 · 6167e99
diff --git a/zddc/internal/apps/embedded/classifier.html b/zddc/internal/apps/embedded/classifier.html index 3ad2459..980c8c0 100644 --- a/zddc/internal/apps/embedded/classifier.html +++ b/zddc/internal/apps/embedded/classifier.html @@ -1376,7 +1376,7 @@ body.help-open .app-header {
ZDDC Classifier - v0.0.9-alpha · 2026-05-02 · 76820fa + v0.0.9-alpha · 2026-05-02 · 6167e99
diff --git a/zddc/internal/apps/embedded/index.html b/zddc/internal/apps/embedded/index.html index 628e55f..1df7e77 100644 --- a/zddc/internal/apps/embedded/index.html +++ b/zddc/internal/apps/embedded/index.html @@ -866,7 +866,7 @@ body { ZDDC Archive - v0.0.9-alpha · 2026-05-02 · 76820fa + v0.0.9-alpha · 2026-05-02 · 6167e99
diff --git a/zddc/internal/apps/embedded/mdedit.html b/zddc/internal/apps/embedded/mdedit.html index 637cfb8..40affdc 100644 --- a/zddc/internal/apps/embedded/mdedit.html +++ b/zddc/internal/apps/embedded/mdedit.html @@ -1774,7 +1774,7 @@ body.help-open .app-header {
ZDDC Markdown - v0.0.9-alpha · 2026-05-02 · 76820fa + v0.0.9-alpha · 2026-05-02 · 6167e99
diff --git a/zddc/internal/apps/embedded/transmittal.html b/zddc/internal/apps/embedded/transmittal.html index 0527598..9257b78 100644 --- a/zddc/internal/apps/embedded/transmittal.html +++ b/zddc/internal/apps/embedded/transmittal.html @@ -2210,7 +2210,7 @@ dialog.modal--narrow {
ZDDC Transmittal - v0.0.9-alpha · 2026-05-02 · 76820fa + v0.0.9-alpha · 2026-05-02 · 6167e99
diff --git a/zddc/internal/apps/embedded/versions.txt b/zddc/internal/apps/embedded/versions.txt index 4b23839..973d5cb 100644 --- a/zddc/internal/apps/embedded/versions.txt +++ b/zddc/internal/apps/embedded/versions.txt @@ -1,6 +1,6 @@ # Generated by build.sh — do not edit. One = per line. -archive=v0.0.9-alpha · 2026-05-02 · 76820fa -transmittal=v0.0.9-alpha · 2026-05-02 · 76820fa -classifier=v0.0.9-alpha · 2026-05-02 · 76820fa -mdedit=v0.0.9-alpha · 2026-05-02 · 76820fa -landing=v0.0.9-alpha · 2026-05-02 · 76820fa +archive=v0.0.9-alpha · 2026-05-02 · 6167e99 +transmittal=v0.0.9-alpha · 2026-05-02 · 6167e99 +classifier=v0.0.9-alpha · 2026-05-02 · 6167e99 +mdedit=v0.0.9-alpha · 2026-05-02 · 6167e99 +landing=v0.0.9-alpha · 2026-05-02 · 6167e99