ZDDC
bdac8dc4fb
The 2dc9ad2 commit ("refactor: distribute via Codeberg release assets,
drop the upstream image") rewrote AGENTS.md and CLAUDE.md but left
several pre-existing references to the old write-to-website/releases
flow and the now-removed Containerfile / podman-compose / release-image.sh.
This sweeps the rest:
- CLAUDE.md
- drop "podman/podman-compose" from the zddc/ blurb (no Containerfile)
- drop the broken `podman build -t zddc-server zddc/` command
- rewrite the "Most-used commands" table so --release semantics match
actual behavior (tag + Codeberg upload, not file write)
- rewrite "Things that bite": replace "never write to website/releases/"
and the obsolete "alpha exception" bullet with the new rules
($CODEBERG_TOKEN required, dist files no longer force-tracked, etc.)
- rewrite the website/ description in "Repo shape" to reflect that
only index.html + manifest.json live there now
- ARCHITECTURE.md
- rewrite the website/ directory tree (no more <tool>_v*.html, _stable
symlinks, or _alpha/_beta files)
- rewrite "Channels" section: every cut now tags + uploads to Codeberg,
alpha/beta have .N counters and matching tags, no more in-place
overwrites
- rewrite the build-label table: dev builds carry the next-stable
target as a -alpha pre-release suffix with full timestamp + dirty
marker (was: "Built: <ts> BETA")
- update level-2 bootstrap description: resolves channel via
manifest.json, fetches /releases/<tag>/<asset>, not a flat URL
- update landing-tool description: ships only as Codeberg release
asset, not a committed website/releases/landing_v<X>.html
- AGENTS.md
- update website/ tree to the post-refactor layout
- replace the two-step podman build / podman-compose run blocks under
zddc-server with a Go build + go run quickstart (no container in
this repo)
- drop the "Containerfile uses a multi-stage build" note from the
"Notes" list (Containerfile is gone)
- drop the stale "landing/build.sh writes website/index.html" note —
website/index.html is now hand-edited, not produced by landing's
build
- README.md (top-level)
- tools table no longer links to /releases/<tool>_stable.html
(those URLs return 404 post-refactor); link to the releases page
once instead
- bootstrap/README.md
- update the "permanent pin" URL examples and CORS verification
snippet to use /releases/<tag>/<asset> URLs (Caddy → Codeberg)
instead of the old flat /releases/<tool>_<channel>.html pattern
- explain that channel resolution is via manifest.json now
- zddc/README.md
- rewrite Quick Start: download a release binary or build from source,
no `podman build`
- rewrite TLS examples to invoke ./zddc-server directly instead of
`podman run ... zddc-server` (image name no longer exists)
- mention ZDDC_INSECURE_DIRECT in the env-var table and the plain-HTTP
example — startup is refused without it on non-loopback binds
- replace the "Container image" section with "Distribution" (binaries
on Codeberg, no image) and the "Building" section with go build
instructions
- replace "Release Tagging" with documentation of zddc/release.sh
(the canonical replacement for release-image.sh, which is gone)
- shared/build-lib.sh
- fix the comment claiming "plain builds mirror to website/releases/"
— they don't anymore
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
55 lines
6.6 KiB
Markdown
55 lines
6.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|