Deadworks Relay

Step 4: Apply Changes In Layers

Work outside-in. Do not start from the UI; types must flow downward.

1. Relay client schemas (packages/relay-client/src/schemas.ts)
   • Mirror the spec exactly. This package is the boundary with the relay mesh.
   • Use .optional().default(...) for fields the spec marks optional with a documented default; use plain .optional() otherwise.
   • Run pnpm --filter @deadlock-mods/relay-client build (or tsgo --noEmit) to type-check.
2. Relay client transport (packages/relay-client/src/client.ts)
   • Add/remove methods to match new endpoints (e.g. if events, auth challenge, or gossip endpoints become client-relevant).
   • Keep the circuit breaker and retry behavior — those are DMM concerns, not protocol.
3. Shared schemas (packages/shared/src/schemas/server-browser.schemas.ts)
   • The DMM-facing schema extends the relay shape with aggregation fields (source_relay, source_region). Keep those.
   • Mirror any field additions/renames from the relay schemas.
4. API services (apps/api/src/services/*.ts)
   • server-browser.ts: dedup logic keys on id; touch only if pagination/sorting fields change.
   • server-mods-resolver.ts: rewrite parser whenever ModRequirement shape changes (see drift section above).
   • relay-discovery.ts: only changes if relays.json shape or /api/v1/relays shape changes.
5. API router (apps/api/src/routers/v2/servers.ts)
   • oRPC types are derived from the schemas, so this rarely changes — but rebuild types and check the output.
6. Desktop API client (apps/desktop/src/lib/api.ts)
   • Type imports flow from @deadlock-mods/shared. If schemas were renamed, update imports.
7. Desktop hooks and components
   • Find every component that reads a changed field: rg "required_mods\.|server\.auth_|gateway_url|connect_code|password_protected" apps/desktop/src/components/server-browser
   • Update display logic. Respect i18n: any new user-facing string must go through react-i18next (see apps/desktop/src/locales/).

Step 5: Cache & Compatibility

The API aggregator caches list/detail responses in Redis (CACHE_TTL.SERVERS_LIST, CACHE_TTL.SERVER_DETAIL, CACHE_TTL.SERVERS_FACETS). When response shape changes:

• Bump cache key versions in apps/api/src/services/server-browser.ts (buildListCacheKey, the literal server-browser:detail: and server-browser:facets) — e.g. server-browser:v2:detail:. This avoids serving stale payloads parsed against the new schema.
• Document the bump in the changeset.

Step 6: Verify

Run each of these and fix issues before stopping:

pnpm --filter @deadlock-mods/relay-client check-types
pnpm --filter @deadlock-mods/shared check-types
pnpm --filter @deadlock-mods/api check-types
pnpm --filter @deadlock-mods/desktop check-types
pnpm lint:fix
pnpm format:fix

Then exercise the path manually if changes are user-visible:

1. Start the local relay sim per ../deadworks-relay/README.md:

   cd ../deadworks-relay && bun install && bun run sim:dev

2. Point DMM API at it (RELAYS_JSON_URL=http://127.0.0.1:3000/relays.json or the local seed file).
3. Open the server browser tab in the desktop app and confirm:
   • List renders, region/game-mode/password filters work.
   • Detail panel shows mods, required mods, players.
   • Join action: gateway URL opens externally if present; otherwise connect code copies.
   • Auth-protected servers show the shield icon and prompt message.

If the relay sim is not available, at minimum write a Vitest case that parses a fixture payload generated from ../deadworks-relay/packages/protocol/src/index.ts types.

Step 7: Changeset

Per .cursor/rules/090-changesets.mdc, create a changeset for any user-visible change. Use a minor bump if the public DMM API client surface changes; patch otherwise.

Example body:

Sync relay client and server browser with Deadworks Relay protocol v1
spec at <commit-or-date>. Updates `required_mods` shape to
`{ id, provider, url, version }` and adjusts the resolver to parse
GameBanana IDs from `url` instead of `name`. Bumps server browser
cache keys to invalidate stale Redis payloads.

Hard Rules

• NEVER read the deadworks-relay TS sources by guessing — always re-read protocol/src/index.ts and spec/PROTOCOL.md at the start of the task. The spec evolves between runs of this skill.
• NEVER rename a field in only one layer. If required_mods[].id changes, update the relay-client schema, shared schema, resolver, and every UI consumer in the same change.
• NEVER weaken validation by switching strict zod fields to z.any() to silence type errors. If the spec genuinely allows arbitrary shape, use z.unknown() and gate consumers explicitly.
• NEVER drop the source_relay / source_region fields from the DMM-facing schemas — those are DMM's aggregation metadata, not part of the relay spec.
• NEVER hand-edit anything inside ../deadworks-relay/. It is a sibling repo and not part of this workspace.
• ALWAYS bump cache key versions (Step 5) when response shape changes. Stale Redis payloads parsed against a new zod schema will break the API.
• ALWAYS run the check-types commands in Step 6 before declaring done.