ZDDC/CLAUDE.md

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; Go 1.24+). Serves ZDDC_ROOT/index.html at GET / as the landing page; Accept: application/json on / returns the ACL-filtered project list. Released as cross-compiled binaries on Codeberg (no container image — the chart Dockerfiles compile from source at deploy time).
• shared/ — base.css plus shared JS modules (zddc.js, hash.js, zddc-filter.js, theme.js, help.js) included by every tool's build, build-lib.sh (POSIX sh helpers sourced by every tool's build.sh), and publish-codeberg-release.sh (the create-release-and-upload-asset helper used by both build-lib.sh and zddc/release.sh).
• website/ — published artifacts: index.html (root URL), releases/index.html + releases/manifest.json (regenerated by build.sh from the Codeberg API; the manifest maps <tool>-<channel> → tag for runtime channel resolution), and bootstrap/{level1,track-stable,track-beta,track-alpha}/<tool>.html (per-channel level-2 stubs + same-origin level-1 stubs that the home-page install snippets curl into the operator's deployment dir). The actual built tool HTML and zddc-server binaries live on Codeberg as release assets — Caddy at zddc.varasys.io reverse-proxies /releases/<tag>/<asset> to the corresponding Codeberg URL. bootstrap/ is regenerated by every plain sh build.sh. 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) + regen releases index/manifest
sh tool/build.sh                            # build one (archive|transmittal|classifier|mdedit|landing)
sh tool/build.sh --release [version]        # cut stable; tag <tool>-vX.Y.Z and upload <tool>_vX.Y.Z.html to Codeberg
sh tool/build.sh --release alpha|beta       # cut channel build; tag <tool>-vX.Y.Z-{alpha,beta}.N and upload to Codeberg
./freshen-channel <tool> <channel>          # rebuild alpha/beta from current stable tag (run after every stable release)
npm test                                    # all Playwright specs (build first!)
npx playwright test <tool>                  # one spec
./dev-server start  # ./dev-server stop     # cache-busting HTTP on :8000

# zddc/ Go server (separate sub-project, not part of sh build.sh)
(cd zddc && go test ./...)                  # unit tests (Go 1.24+)
sh zddc/release.sh [alpha|beta|stable] [<version>] # cut + publish zddc-server binaries to Codeberg release assets (default: alpha; auto-derives version)

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

Things that bite if you forget

• dist/ is gitignored. tool/dist/<tool>.html is the canonical built artifact for testing and as the source for --release uploads. Never hand-edit a dist/ file.
• Codeberg is the canonical store for release assets. --release is the only path to publishing — it tags the commit and uploads the dist HTML (or zddc-server binaries) to Codeberg via shared/publish-codeberg-release.sh. Nothing under website/releases/ other than index.html and manifest.json is checked in; the *.html per-version files and zddc-server binaries are gitignored. Don't reintroduce them.
• $CODEBERG_TOKEN must be exported before any --release invocation. Without it, publish_codeberg_release aborts with a clear error.
• Pre-release semver for alpha/beta. On-page label embeds vX.Y.Z-{alpha,beta} where X.Y.Z is the next-stable target (patch+1 from latest clean <tool>-vX.Y.Z tag). Every alpha/beta cut is tagged with a .N counter (<tool>-v0.0.3-alpha.1, .2, …) that resets when the next stable is cut. Stable tags are clean <tool>-vX.Y.Z.
• Plain sh tool/build.sh is a dev build. The on-page label says vX.Y.Z-alpha · <full-ts> · <sha>[-dirty] (full timestamp + dirty marker distinguish iterative dev work from a formal --release alpha cut), but no Codeberg upload happens. To publish, re-run with --release alpha.
• 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.