ZDDC 91d6e61e22 feat(web): releases index, alpha+beta channel builds, inline server section

Three things on the public website:

1) Cut alpha and beta channel builds for all five tools, so each tool
   now has stable + beta + alpha actually published — previously
   beta and alpha were vapor for archive (which had been freshened
   earlier) and missing entirely for the others. The intro page's
   tool cards now point at real artifacts on every channel.

2) New website/releases/index.html — a generated index of every
   version + channel of every tool, with stable/beta/alpha pill
   links per tool and a "Pin to version" row of every concrete
   v0.0.X build. Regenerated by build.sh's new build_releases_index
   function (reads the filesystem so it is always consistent with
   what is actually under releases/). Linked from the intro page nav
   (Releases), from the bottom of the Try the tools section
   ("Browse all versions"), and from the Learn more list.
   reference.html's nav gets the same Releases link.

3) Folded website/zddc-server.html into website/index.html as a new
   inline section ("zddc-server (optional)") below the tool cards.
   The earlier separate page is removed; the broken Server nav link
   that pointed at it is gone too. The new section leads with the
   dual-mode insight (the tools work locally on a folder OR via any
   web server, including the optional zddc-server) and frames
   zddc-server as a small Go binary that adds things a generic web
   server cannot: ACL via .zddc files, virtual .archive URL space,
   per-request access logging, mundane glue. The What is it?
   paragraph also mentions the dual-mode story up front so users
   reading top-to-bottom get the framing before they hit the cards.

Also caught two stale _latest.html refs missed by the earlier
rename sweep: 8 tool links in reference.html and a comment line in
CLAUDE.md. Verified with a full link audit — every relative href in
index.html, reference.html, and releases/index.html now resolves to
an existing file under website/.

ARCHITECTURE.md doc-ownership table updated: zddc-server.html row
removed; new row added for the regenerated releases/index.html.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-28 10:00:10 -05:00

4.6 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Authoritative docs — read these first

This repo already has two thorough agent-facing references. Always consult them before working — they cover details intentionally omitted here:

AGENTS.md — commands, build-system rules, per-tool parser quirks, testing gotchas, git/worktree workflow, release process, zddc-server notes
ARCHITECTURE.md — single-file HTML pattern rationale, JS module/state patterns, per-tool architecture, security model

If something in this CLAUDE.md conflicts with those, those win — and please update them rather than letting drift accumulate.

Repo shape

This is a monorepo of independent tools, not one application:

archive/, transmittal/, classifier/, mdedit/, landing/ — five self-contained HTML tools, each compiled to a single inlined HTML file in its own dist/. Naming: the first four output dist/tool.html; landing/ outputs dist/index.html (it's the project picker served at the root of zddc-server).
zddc/ — Go HTTP server (separate sub-project, podman/podman-compose; Go 1.24+). Serves ZDDC_ROOT/index.html at GET / as the landing page; Accept: application/json on / returns the ACL-filtered project list.
shared/ — base.css plus shared JS modules (zddc.js, hash.js, zddc-filter.js, theme.js, help.js) included by every tool's build, and build-lib.sh (POSIX sh helpers sourced by every tool's build.sh)
website/ — published artifacts: index.html (root URL), releases/<tool>_v<X.Y.Z>.html (immutable stable archives), releases/<tool>_stable.html (symlink to current stable), releases/<tool>_{alpha,beta}.html (mutable channel files), plus bootstrap zips (install.zip, track-{alpha,beta,stable}.zip). --release is the only path to publishing — there is no website/dev/.
tests/ — Playwright specs (Chromium only, requires File System Access API). tests/schema.spec.js validates transmittal.schema.json against canonical fixtures via ajv (only dev dep besides Playwright)

Most-used commands

sh build.sh                                 # build all five HTML tools (dist/ only)
sh tool/build.sh                            # build one (archive|transmittal|classifier|mdedit|landing)
sh tool/build.sh --release [version]        # cut stable; tag, write website/releases/<tool>_v<ver>.html, refresh _stable symlink
sh tool/build.sh --release alpha|beta       # cut channel build; overwrites website/releases/<tool>_<channel>.html (mutable, no tag)
npm test                                    # all Playwright specs (build first!)
npx playwright test <tool>                  # one spec
./dev-server start  # ./dev-server stop     # cache-busting HTTP on :8000

No lint/typecheck/format commands exist — vanilla JS + POSIX sh by design.

Things that bite if you forget

dist/ is gitignored but force-committed (git add -f tool/dist/tool.html). Never hand-edit a dist/ file.
Never write to website/index.html or website/releases/* directly — promote via sh tool/build.sh --release [version|alpha|beta]. Stable releases write website/releases/<tool>_v<ver>.html (immutable) and refresh <tool>_stable.html; alpha/beta overwrite <tool>_<channel>.html in place.
Always build before running tests — Playwright opens dist/tool.html via file://.
</ in JS string/template literals breaks inline <script> 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.
Two globals only: window.app (per-tool app state + modules) and window.zddc (shared library). No others — anything that crosses tool boundaries goes through one of these.
Worktrees live at ~/src/zddc-<branch>. Check git worktree list before starting a feature branch; never git checkout/switch inside a worktree another agent might be using.
Build scripts are POSIX sh with set -eu, not bash. concat_files takes positional args only.