A private, Git-backed lead-sheet and set-list PWA for cover-band vocalists.
Live app: https://kgl-songs.exe.xyz/
Phases 0 and 1 are implemented as of August 6, 2026:
- 284 legacy Markdown lead sheets migrated byte-for-byte into
songs/. - The 32-song Murphys set migrated into
sets/2021-02-20-murphys.md. - 59 historical Set List drafts imported from GitHub, Notion, and the private Band archive, for 60 visible Set Lists total.
- Draft Set Lists preserve unresolved songs in place, support month-precision dates, can be reordered, and show lead-sheet placeholders in live mode.
- 293 API-visible Notion lead sheets exported as review-only Markdown candidates under
migration/notion-candidates/. - Apex 1.1.14 renders every canonical song and every Notion candidate.
- Searchable read-only song library and set-list views.
- Automatic full-library offline snapshots keep every song, Set List, and Live page available after a verified download; updates are staged atomically so a failed refresh preserves the previous complete snapshot.
- Offline status on About reports snapshot revision, resource count, size, refresh time, and browser-persistence state.
- Song search includes artist names; Set Lists can be searched by title, date, or location.
- Stage-dark and bright-outdoor themes.
- iPad/tablet live sheets use exactly two columns and fit to one viewport at a 16px readability floor.
- iPhone uses exactly one 20px column with vertical scrolling when required.
- A standalone
<!-- column-break -->comment starts the next tablet column in lead sheets and set lists; it is ignored in one-column phone layouts. - Set-list entries support gig-specific
— singer: Name — key: D — bpm: 132 — note: Detailsfields. Key falls back to the lead sheet when omitted; BPM appears only when explicitly reviewed for that performance. - A Set-column heading uses
## Set 1 — Slowimmediately before its first song; later headings follow a standalone<!-- column-break -->. - Individual Set Lists can be edited as canonical Markdown or maintained with Add song, Remove songs, and drag-to-reorder controls; every save validates, commits, pushes, and reindexes.
See Phase 0–1 results, the v1 implementation proposal, and the v2 architecture and product proposal.
make test
make build
./srv/songs -listen :8000 -repo .The service expects Apex on PATH and stores its rebuildable SQLite index under var/. Markdown in Git remains canonical.
# Verify the running service, representative pages, and an offline resource hash
./scripts/smoke-test.sh
# Build an immutable release, preflight it on a separate port, switch atomically,
# and restore the previous release automatically if production checks fail
./scripts/deploy-v1.sh
# Clone origin/main into a temporary directory, rebuild SQLite, launch it, and smoke-test it
./scripts/restore-drill.shProduction serves the binary, templates, and static assets from the immutable
var/current-release symlink. songs-restore-drill.timer runs the remote
restore drill weekly after it is installed and enabled.
songs/ canonical migrated lead sheets
sets/ canonical Markdown set lists
migration/notion-candidates/ review-only Notion exports
migration/ migration manifests and reports
scripts/ Notion export tooling
tools/ legacy migration tooling
srv/ Go server, templates, PWA assets
# Reproduce or verify the byte-preserving legacy migration
python3 tools/migrate_legacy.py
python3 tools/migrate_legacy.py --verify-only
# Refresh review-only Notion candidates and validate with Apex
python3 scripts/export_notion_lead_sheet_candidates.py --validate-apex- Phase 0–1 implementation report
- V2 architecture and product proposal
- V1 implementation proposal
- Lyrics provider policy
- Focused Shelley edits
- Legacy migration instructions
- Notion audit
- Legacy repository audit
- Environment record
V1 uses exe.dev authentication headers for a single owner/viewer boundary. The
address in SONGS_OWNER_EMAIL is the only account allowed to create, edit,
reorder, import, invoke Shelley changes, or reindex. Other authenticated
exe.dev Web-share users can browse, print, use Live mode, and use the automatically
prepared full offline library; mutation and editor endpoints return 403 Forbidden.
The production service binds to loopback so authenticated exe.dev HTTPS is the only external entry point.
The old loosely-covered/set-lists repository contains a tracked plaintext Snowflake credential and a workflow step that can expose a secret in logs. Rotate/revoke affected credentials and remove them from current content and Git history. No secret values are copied into this repository.