Skip to content

feat(catalog): global exercise catalog with slugs - #89

Merged
mohammadp1001 merged 2 commits into
mainfrom
feat/72-exercise-catalog
Aug 22, 2026
Merged

feat(catalog): global exercise catalog with slugs#89
mohammadp1001 merged 2 commits into
mainfrom
feat/72-exercise-catalog

Conversation

@mohammadp1001

Copy link
Copy Markdown
Owner

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.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 repo changed under us, and a deploy
must not depend on a third-party URL being reachable.

649 exercises, from 873 upstream:

Dropped Count Why
stretching, cardio, plyometrics, strongman 219 The program format and hard-set volume model both assume sets × reps. A stretch logged as "3 × 10 at 0kg" would count toward weekly volume as though it were training.
neck exercises 5 Our muscle vocabulary has no neck. Mapping them to something adjacent would be inventing anatomy.

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 push and never runs migrate deploy (HANDOFF, "Prisma migrations"), so a data migration would never reach
it.

npm run db:seed-catalog is idempotent and safe to run repeatedly. CI runs it
after migrating. Re-seeding deliberately leaves tips, mistakes and
videoUrl untouched - they are empty in the import and exist to be curated by
hand, and a re-seed must not wipe that work.

⚠️ Production needs npm run db:seed-catalog run once against Neon, the
same way the v0.4.2 migration was applied by hand. Nothing breaks until #74
starts reading from the catalog, but it should not be forgotten.

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), slugs
are 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. Validation
rejects 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 --noEmit and eslint clean.

Nothing in the app writes to this table.

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.
@mohammadp1001
mohammadp1001 merged commit 34e1c22 into main Aug 22, 2026
2 checks passed
@mohammadp1001
mohammadp1001 deleted the feat/72-exercise-catalog branch August 22, 2026 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Global exercise catalog with slugs

1 participant