# Trpc Compat

Check that a tRPC change is safe for released desktop, mobile, CLI, and SDK builds...

- Repository: https://github.com/ParadevAI/Paradev (15823 stars)
- Category: DevOps
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ParadevAI/Paradev --skill trpc-compat -g -a claude-code -y`
Codex: `npx skills add ParadevAI/Paradev --skill trpc-compat -g -a codex -y`
Cursor: `npx skills add ParadevAI/Paradev --skill trpc-compat -g -a cursor -y`
Gemini CLI: `npx skills add ParadevAI/Paradev --skill trpc-compat -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add ParadevAI/Paradev`

## Description

Check that a tRPC change is safe for released desktop, mobile, CLI, and SDK builds, pick the compatible pattern, and decide when a deprecated procedure can be removed. Use when changing, renaming, or removing an existing procedure, input field, or output field in packages/trpc or packages/host-service, when reviewing such a PR, or when a deploy broke released clients.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# tRPC compatibility

On 2026-09-23, #7726 changed `page.list` from a bare array to `{ items, nextCursor }`. It
updated every caller on main, so typecheck and tests passed. Desktop 1.30.0, 1.30.2 still called
`.map` on the result, and every workspace view crashed (SEV1, 337 Sentry events, postmortem
"page.list response change crashed released desktop apps"). CI only sees main. This skill is how
you check the builds CI cannot see.

## 1. Find released callers

Search the release tags, not main. Run `git fetch --tags` first in a fresh clone.

```bash
PROC='page\.list(?!Paginated)'   # the procedure path; exclude longer names that share the prefix
FLOOR=1.29.0                     # MINIMUM_DESKTOP_VERSION in apps/api/src/app/api/desktop/version/route.ts
for v in $({ echo "$FLOOR"; git tag -l 'desktop-v*' | sed 's/^desktop-v//'; } | awk '!/-/' | sort -uV | sed -n "/^$FLOOR\$/,\$p"); do
  git rev-parse -q --verify "refs/tags/desktop-v$v" >/dev/null || continue
  git grep -q -P "$PROC" "desktop-v$v" -- apps/desktop && echo "desktop-v$v calls it"
done
```

- **Desktop**: every `desktop-v*` tag at or above the floor is live.
- **CLI**: same loop with `cli-v*` tags and `-- packages/cli`. The CLI has no floor, so check
  every tag you can; old installs stay in use.
- **Mobile**: no tags, and `MINIMUM_MOBILE_VERSION` is `1.0.0`. If `apps/mobile` on main calls it,
  or `git log -S` shows it ever did, treat it as called by a live build.
- **SDK**: `packages/sdk` calls procedures by string (`/api/trpc/<procedure>`). Search main and
  `git log -S` the same way.
- **host-service** procedures: callers are desktop, CLI, and mobile, and the host can be older or
  newer than the client. See `packages/host-service/AGENTS.md`.

Any hit means the procedure is live. Its input and output are frozen.

## 2. Check usage data

The API samples 1% of calls into the PostHog event `api_procedure_called`. Run this in the
PostHog SQL editor or through the PostHog MCP:

The rest: https://github.com/ParadevAI/Paradev/blob/HEAD/.agents/skills/trpc-compat/SKILL.md