Add Zod-based type safety to bundle search route

[shwetank-dev]

Summary

• Add BundleSearchQuerySchema in schemas/query.ts using Zod with proper enum constraints (type: node/python/binary, sort: downloads/recent/name) and min/max validation for limit (1-100) and offset (>=0)
• Replace hand-written JSON Schema querystring with toJsonSchema(BundleSearchQuerySchema) in the /v1/bundles/search route
• Make the handler type-safe via Fastify <{ Querystring: BundleSearchQuery }> generic — removes the manual as { ... } cast
• Use PackageSearchFilters instead of Record<string, unknown> for filters
• Replace if/else sort chain with explicit sort map lookup — all sort options are now visible in one place, no hidden default in a let initializer
• Remove runtime clamping (Math.max/Math.min) — validation is now enforced at the schema level, invalid values return 400 instead of being silently corrected
• Update test to verify 400 rejection for invalid pagination instead of clamping behavior

Design decisions & tradeoffs discussed

optional() + default() ordering in Zod

• z.optional(z.string().default(...)) wraps default inside optional → output type includes undefined
• z.string().optional().default(...) puts default on the outside → output type is always concrete
• We use the latter so the handler sees sort: "downloads" | "recent" | "name" (never undefined), while the JSON Schema still marks the field as not required (user can omit it)

Schema validation vs silent clamping

• Previously invalid values like limit=0 were silently clamped to 1 — the client got unexpected results with no indication their input was wrong
• Now Zod's min(1).max(100) rejects bad values with a 400, which is more correct API behavior

Response type safety — current limitations

• Runtime: Fastify's response schema (toJsonSchema(BundleSearchResponseSchema)) does serialization/stripping of extra fields but does not validate the response shape — if the handler returns the wrong structure, it won't throw
• Compile-time: Fastify's Reply generic can type reply.send(), but does not enforce return types from async handlers — so there's no compile-time check that the handler returns the correct shape
• Recommendation: Use Zod response schemas in tests to verify handler output shape rather than adding runtime validation overhead in production

Where should the abstraction between DB fields and API fields live?

• Currently the handler manually maps between query params → Prisma filters and Prisma results → API response shape
• Two approaches discussed:
  1. Repository layer: Add methods like searchBundles() that accept query params directly and return API-shaped types (e.g. BundleSearchItem[]). Keeps handlers thin, but couples the repo to the API shape
  2. Separate helpers/mappers: Keep the repo returning Prisma types, add a mapping layer between repo and handler. More separation of concerns but more files
• This PR does not change the repo layer — left for follow-up discussion

Where should query schemas live? (open question)

• Currently in apps/registry/src/schemas/query.ts — co-located with the registry app
• Could move to packages/schemas/ alongside the shared response schemas, then generate/export from there — this would allow the SDK and CLI to share the same query types
• Needs discussion on whether query schemas are app-specific or shared across consumers

Test plan

• pnpm --filter @nimblebrain/mpak-registry test — all 80 tests pass
• Manual test: curl 'http://localhost:3200/v1/bundles/search?q=echo' returns results with defaults applied
• Manual test: curl 'http://localhost:3200/v1/bundles/search?limit=0' returns 400
• Manual test: curl 'http://localhost:3200/v1/bundles/search?type=rust' returns 400
• Manual test: curl 'http://localhost:3200/v1/bundles/search?sort=popularity' returns 400

🤖 Generated with Claude Code

[mgoldsborough]

This needs to be in packages/shcmeas

[shwetank-dev]

Some confusion on how schemas are copy over to generated

[mgoldsborough]

add limit to the elngth

[shwetank-dev]

Done

[mgoldsborough]

TODO: we should refactor this to be .findPackage(name, os, arch)

Then check for pkg and/or artifacts === undefined