feat/file-migrations

[MD4]

Description

Adds a file migration system so model changes that alter JSON shape no longer break loading of existing ~/.ptah/ resources (settings, shows, programs). Files are stamped with the app version; on load the repository runs an app-version-keyed migration chain over the raw JSON, backs up the original under ~/.ptah/.backups/, writes the upgraded file back, then validates with the existing Zod model. Ships the first real migration, fixing program loading broken by the targetIntput → targetInput edge-field rename in #218.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe):

Changes Made

• Migration engine (packages/lib-shared/src/migrations/): pure runMigrations(raw, chain, {from, to}) applying migrations in (from, to] ascending semver order + re-stamping; small semver.ts comparator (no new dep).
• Version stamping: BASELINE_VERSION + getCurrentAppVersion() in lib-models; optional version field on the show & program models; createSettings stamps the current version.
• Lazy load + write-back with backup: repositories/migrate-resource.ts (loadAndMigrate) wired into the show, program, and settings repositories; saves stamp the current version. Backups land at ~/.ptah/.backups/<resource>/<name>.<oldversion>.json.
• First migration: targetIntput → targetInput for programs (idempotent), keyed to 0.3.0 so it runs on legacy/baseline files (feat/tests-and-bugs #218).
• Changeset: minor bump (app, lib-models, lib-shared, lib-domains) → 0.3.0, matching the migration's target version.
• Docs: "File migrations" authoring recipe in AGENTS.md; design + plan under docs/superpowers/.

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed

Added 26 lib-shared tests (semver, engine, program migration, loadAndMigrate, and per-repository temp-dir integration covering legacy migration, version stamping, and backup behavior) plus model/domain test updates. pnpm allcheck passes (10/10 tasks: format → lint → typecheck → build → test).

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex code
• Documentation updated
• No new warnings generated
• Tests pass locally

Related Issues

Fixes the program-loading regression introduced by #218 (targetIntput → targetInput).

Additional Notes

• Migration-authoring recipe (now in AGENTS.md): when a model change breaks an old file, add one { version, up } entry to that resource's chain in lib-shared/src/migrations/, write up against plain JSON and make it idempotent, add a fixture test, and bump the app version via changeset. Migrations only run for files stamped older than the current APP_VERSION.
• One-time rewrite on first load: legacy/unstamped files are backed up and re-stamped once the first time they're loaded after this ships.
• Local env caveat: pnpm i aborts on the midi package's native rebuild (node-gyp missing locally); it does not affect build/test (pnpm allcheck is green) since service-midi mocks the binding in tests.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.86%. Comparing base (dbd8740) to head (c057f8b).
⚠️ Report is 21 commits behind head on master.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #241      +/-   ##
==========================================
- Coverage   91.28%   89.86%   -1.43%     
==========================================
  Files          32       45      +13     
  Lines         574      730     +156     
  Branches       65       81      +16     
==========================================
+ Hits          524      656     +132     
- Misses         50       74      +24     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.