chore(db): generate prisma client on postinstall

[joryirving]

Summary

• Add "postinstall": "prisma generate" so a fresh clone / any schema change never leaves a stale client.
• Stop prisma.config.ts throwing when DATABASE_URL is unset (it's loaded by prisma generate, which needs only the schema) — supply datasource.url only when present.

Why

On a fresh checkout, tsc/test/dev failed with Property 'groomingRun' is missing on PrismaClient (stale generated client) until you manually npm run db:generate. The throw in prisma.config.ts also meant generate itself failed on a machine with no env. Runtime still enforces DATABASE_URL via src/lib/prisma.ts; migrate/deploy still read it from env.

Verification

• With DATABASE_URL unset: prisma generate now succeeds (previously threw).
• tsc --noEmit → exit 0.

Closes #499

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M2.7@https://litellm.jory.dev/v1 (anthropic) — escalated (fast_low_confidence)

Recommendation

Approve. This PR correctly implements the fix for issue PR 499, addressing the real problem where fresh clones fail on npm install because prisma generate (run during postinstall) threw when DATABASE_URL was not set. The solution is well-reasoned, internally consistent, and properly documented.

Change-by-Change Findings

prisma.config.ts

• Removes the hard throw when DATABASE_URL is unset and makes the datasource config conditional via spread operator.
• Rationale: prisma generate only needs the schema file to produce client types — it does not need a live database connection. Throwing here broke the npm install → postinstall → generate flow on fresh clones.
• Runtime safety preserved: src/lib/prisma.ts (verified via tool harness) still enforces DATABASE_URL (or DISPATCH_DATABASE_URL) at runtime via initClient(), so the app will fail with a clear error if the env var is missing when it actually tries to connect.
• The explanatory comment is thorough and accurately describes the design rationale.

package.json

• Adds "postinstall": "test -f prisma/schema.prisma && prisma generate || true" script.
• The guard (test -f prisma/schema.prisma) ensures it only runs when the schema exists (e.g., not during package publication).
• The || true prevents install failure if generate fails for any unexpected reason (graceful degradation).
• Uses POSIX shell syntax appropriate for the documented Debian bookworm-slim Docker target.

AGENTS.md

• Updates documentation to reflect the new workflow:
  • npm install now notes it runs prisma generate via postinstall.
  • Replaces npx prisma generate with npm run db:generate and clarifies it also runs on postinstall.
• Aligns with the actual package.json scripts.

Standards Compliance

• No secrets committed: ✅ No credentials or env vars added.
• Prisma schema conventions: ✅ No schema changes; config change is consistent with the Prisma notes in AGENTS.md.
• Error handling: ✅ Runtime error handling in src/lib/prisma.ts remains intact with meaningful error messages.
• Environment variable resolution: ✅ Follows the documented order (DATABASE_URL > DISPATCH_DATABASE_URL) as enforced at runtime in initClient().
• Documentation: ✅ AGENTS.md updated to reflect the new behavior.

Linked Issue Fit

Issue PR 499 acceptance criteria fully met:

• ✅ Added "postinstall": "prisma generate" to package.json.
• ✅ Fixed prisma.config.ts to not throw when DATABASE_URL is unset.
• ✅ Documented the ordering in AGENTS.md.
• ✅ Verification stated in PR body: prisma generate now succeeds without DATABASE_URL.

CI Check Results

All checks passed:

• Lint: ✅ success
• Build: ✅ success
• Tests: ✅ success
• Typecheck: ✅ success
• Docker Build: ✅ success

Tool Harness Findings

• Verified src/lib/prisma.ts contains the runtime DATABASE_URL enforcement via initClient() — the safety net is intact.
• Verified prisma.config.ts contains the updated conditional datasource configuration.
• Verified package.json contains the new postinstall script.

Unknowns or Needs Verification

• Windows compatibility: The postinstall script uses POSIX shell syntax (test -f ... && ... || true). This works on Linux/macOS and in the Docker container. If Windows development is a requirement, this could be addressed separately (e.g., via a JS-based postinstall script or a platform-conditional approach). Not blocking for the current Debian-based target documented in the repository.