feat(catalog): global exercise catalog with slugs - #89
Merged
Conversation
Exercises were seeded per user, and every program upload overwrote an exercise's muscle tags from the YAML. A sloppy or hallucinated program file could therefore silently re-tag an exercise and quietly corrupt the volume chart. Anatomy is a fact about the exercise, not about the program, so it now lives in one shared, read-only place. `ExerciseCatalog` is keyed on a slug - the durable identity a program will reference, so a display name can be corrected later without breaking anything. Content comes from free-exercise-db (Unlicense, public domain, no attribution required), imported by `scripts/build-catalog.mjs` into `prisma/catalog/exercises.json`, which is checked in. The script never runs at build or deploy time: the catalog must not change because an upstream repository changed under us, and a deploy must not depend on a third-party URL being reachable. 649 exercises, from 873 upstream. Stretching, cardio, plyometrics and strongman are excluded because the program format and the hard-set volume model both assume sets and reps, and a stretch logged as "3 x 10 at 0kg" would count toward weekly volume as though it were training. Five neck exercises are dropped outright - our muscle vocabulary has no neck, and mapping them to something adjacent would be inventing anatomy. The upstream vocabulary is 17 coarse names against our 30 fine-grained muscles, so each maps to the single muscle that best represents it rather than to every muscle it might involve. The source cannot distinguish an incline press from a flat one, so claiming both heads of the pec would be inventing detail it does not have. Volume is unaffected either way: a set counts once per muscle group, and every candidate for a given source name sits in the same group. Seeding is an idempotent script rather than a data migration, because production applies schema with `prisma db push` and never runs `migrate deploy` - a data migration would never reach it. `npm run db:seed-catalog` is safe to run repeatedly, and CI runs it after migrating. Re-seeding deliberately leaves `tips`, `mistakes` and `videoUrl` alone: they are empty in the import and exist to be curated by hand, and a re-seed must not wipe that work. Muscles are validated against the closed vocabulary when the file is read, not merely when it is generated. This is the last point before those values reach a column the volume chart depends on, and a bad tag must fail loudly rather than be discovered as a wrong number months later. Nothing in the app writes to this table.
`--experimental-strip-types` needs Node 22+. The repo already assumed it - `db:seed` has used the same flag for a while - but CI never executed one of those scripts, so the gap went unnoticed until the catalog seed step was added.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #72 - first of slice 2 (the exercise catalog).
Why
Exercises were seeded per user, and every program upload overwrote an
exercise's muscle tags from the YAML. So a sloppy or hallucinated program file
could silently re-tag an exercise and quietly corrupt the volume chart. Anatomy
is a fact about the exercise, not about the program.
The content
free-exercise-db- Unlicense (public domain, no attribution required).Imported by
scripts/build-catalog.mjsintoprisma/catalog/exercises.json,which is checked in. The script never runs at build or deploy time: the
catalog must not change because an upstream repo changed under us, and a deploy
must not depend on a third-party URL being reachable.
649 exercises, from 873 upstream:
The muscle mapping (the part that was reviewed)
Upstream has 17 coarse names; ours has 30 fine-grained muscles. Each
coarse name maps to the single muscle that best represents it, not to every
muscle it might involve -
chest → pec_major_sternal,shoulders → side_delt,biceps → biceps_brachii.Tagging conservatively keeps per-muscle reads honest: the source cannot
distinguish an incline press from a flat one, so claiming both heads of the pec
would be inventing detail it does not have.
Volume is unaffected either way - a set counts once per muscle group, and
every candidate for a given source name sits in the same group.
Seeding: a script, not a data migration
Production applies schema with
prisma db pushand never runsmigrate deploy(HANDOFF, "Prisma migrations"), so a data migration would never reachit.
npm run db:seed-catalogis idempotent and safe to run repeatedly. CI runs itafter migrating. Re-seeding deliberately leaves
tips,mistakesandvideoUrluntouched - they are empty in the import and exist to be curated byhand, and a re-seed must not wipe that work.
Validation
Muscles are checked against the closed vocabulary when the file is read, not
merely when it is generated. That is the last point before these values reach a
column the volume chart depends on - a bad tag must fail loudly, not be found as
a wrong number months later.
Tests
lib/db/catalog.test.ts- the checked-in file is comprehensive (>500), slugsare unique and slug-shaped, every muscle is in the vocabulary, every entry has a
primary muscle, no muscle is both primary and secondary, and the staples
(
barbell_squat,barbell_deadlift, a bench press) are present. Validationrejects an invented muscle, a duplicate slug, a malformed slug and an entry with
no primary muscle. Seeding is idempotent, and re-seeding does not overwrite
curated fields.
Full suite: 369 passed, 0 failed.
tsc --noEmitandeslintclean.Nothing in the app writes to this table.