VARASYS/ZDDC
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ZDDC/CLAUDE.md
ZDDC 67f794e6d0 refactor: rename channel 'latest' to 'stable' across all artifacts 
The 'latest' label for the current-stable channel was inconsistent
with the channel set we use elsewhere (alpha / beta / stable). Rename
to 'stable' so URLs, file names, zip names, and image tags all line
up with the channel terminology used in the bootstrap, AGENTS.md
discipline rules, and chart consumers.

File / artifact renames
- website/releases/<tool>_latest.html → <tool>_stable.html (5 files)
- website/track-latest.zip            → track-stable.zip
- shared/build-lib.sh: promote_release writes/refreshes _stable.html
- bootstrap/level{1,2}.html.tmpl: channels map drops 'latest', keeps
  'stable' as the canonical name. ?v=stable is now the explicit way
  to switch to current-stable for one request (alongside ?v=alpha,
  ?v=beta, and ?v=X.Y.Z).
- build.sh: install.zip sources from <tool>_stable.html; emits
  track-stable.zip instead of track-latest.zip.

Container image (.woodpecker.yml rewritten)
- Tag publishing now cascades:
    zddc-server-vX.Y.Z              → :X.Y.Z, :stable, :beta, :alpha, :latest
    zddc-server-vX.Y.Z-beta.N       → :X.Y.Z-beta.N, :beta, :alpha
    zddc-server-vX.Y.Z-alpha.N      → :X.Y.Z-alpha.N, :alpha
- :stable, :beta, :alpha are now first-class channel pointers; chart
  consumers (e.g. tnd-zddc-chart) can FROM :beta for dev and FROM
  :stable for prod.
- :latest kept as an alias for :stable per Docker convention.

Documentation sweep
- AGENTS.md, ARCHITECTURE.md, CLAUDE.md, README.md
- bootstrap/README.md, zddc/README.md
- website/index.html, website/zddc-server.html
- transmittal/template.html, transmittal/README.md
all updated to reference _stable.html / track-stable.zip / the
'stable' channel name. ARCHITECTURE.md's manual freshen example
points at ./freshen-channel instead of the old git-checkout snippet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-28 09:30:24 -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 _latest 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.