Skip to content
kylelundstedtPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Songs

A private, Git-backed lead-sheet and set-list PWA for cover-band vocalists.

Live app: https://kgl-songs.exe.xyz/

Phase status

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: Details fields. 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 — Slow immediately 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.

Run locally

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.

Operations

# 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.sh

Production 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.

Repository layout

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

Migration commands

# 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

Documentation

Read-only sharing

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.

Security note

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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages