feat(github): add GET_PREVIEW_DEPLOYMENT tool for deployment-based previews

[guitavano]

Problema

Alguns hosts publicam a URL de preview de uma PR só como um GitHub Deployment (deployment_status.environment_url) — não como target_url de commit-status nem como comentário de bot. O caso concreto é a VTEX FastStore WebOps: o preview (https://<hash>--<store>.preview.vtex.app) vive no deployment status de staging, e o pull_request_read do upstream não tem método de deployments. Resultado: o painel de PR do Studio não enxerga esses previews.

Correção

Adiciona a tool first-party GET_PREVIEW_DEPLOYMENT, espelhando exatamente o padrão do já-existente GET_CHECK_RUN (que preenche outro gap do upstream lendo a REST API com o token do próprio caller):

• Lê a REST Deployments API (GET /repos/{owner}/{repo}/deployments?sha= + /deployments/{id}/statuses) com env.MESH_REQUEST_CONTEXT.authorization.
• Varre os deployments do commit do mais novo pro mais antigo e retorna o environment_url do status success mais recente.
• Retorna environmentUrl: null (não erro) quando há deployment mas nenhum publicou url ainda (deploy em andamento).
• Filtro opcional por environment (ex.: staging).
• Mesma validação de segmentos (anti path-injection), headers e mapeamento de erros de check-run.ts; sha validado como hex 7–40.

Registrada em github/server/tools/index.ts.

Testes

• github/server/lib/deployment.test.ts — 12 casos (sucesso, skip até o próximo deployment, in-flight → empty, sem deployments → empty, filtro de environment, encode de segmentos, rejeição de path-injection em owner/repo/sha, token ausente, 403/404/5xx, body ilegível). bun test verde.
• tsc --noEmit: sem novos erros (os existentes são do node_modules/@decocms/runtime, pré-existentes).

Próximo passo (outro repo)

PR companheiro no Studio (decocms/studio) liga essa tool como terceiro fallback de previewUrl em apps/api/src/tools/task-board/prs-get.ts, depois de commit-status e comentários. O host .preview.vtex.app já está no allow-list isTrustedPreviewHost.

🤖 Generated with Claude Code

---

Summary by cubic

Adds a first-party GET_PREVIEW_DEPLOYMENT tool to resolve a commit’s preview URL from GitHub Deployments, enabling previews that are published only as deployment-status environment_url. It scans candidate deployments’ statuses in parallel and surfaces environmentUrl as untrusted output.

• Mirrors GET_CHECK_RUN: reads the REST Deployments API with env.MESH_REQUEST_CONTEXT.authorization, validates owner/repo/sha (and optional environment), and maps 401/403/404/5xx to stable errors. Registers the tool in github/server/tools/index.ts and adds unit tests.
• Scans deployments newest-first; reads each deployment’s statuses concurrently (bounded), skips deployments whose status read fails, and returns the newest success with an environment_url, or environmentUrl: null while a deploy is in flight or no URL is published.
• Security: environmentUrl is untrusted (set by the deployer); consumers must host-validate before showing or navigating.

Rollout

• Call GET_PREVIEW_DEPLOYMENT with a token that grants deployments:read. No changes to existing preview sources.
• Studio will adopt this as a third fallback after commit-status and comments. No migration required.

^{Written for commit a005f66. Summary will update on new commits.}