Implantar na Vercel

Implante qualquer projeto na Vercel. Sempre implante como pré-visualização (não produção), a menos que o usuário solicite explicitamente produção.

O objetivo é colocar o usuário na melhor configuração de longo prazo: seu projeto vinculado à Vercel com implantações via git push. Cada método abaixo tenta mover o usuário mais perto desse estado.

Etapa 1: Coletar o Estado do Projeto

Execute todas as quatro verificações antes de decidir qual método usar:

# 1. Verificar se existe um repositório remoto git
git remote get-url origin 2>/dev/null

# 2. Verificar se está vinculado localmente a um projeto Vercel (qualquer um dos arquivos indica vinculação)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. Verificar se o CLI da Vercel está instalado e autenticado
vercel whoami 2>/dev/null

# 4. Listar equipes disponíveis (se autenticado)
vercel teams list --format json 2>/dev/null

Seleção de equipe

Se o usuário pertencer a várias equipes, apresente todos os slugs de equipe disponíveis como uma lista com marcadores e pergunte em qual implantar. Depois que o usuário escolher uma equipe, prossiga imediatamente para a próxima etapa — não peça confirmação adicional.

Passe o slug da equipe via --scope em todos os comandos subsequentes do CLI (vercel deploy, vercel link, vercel inspect, etc.):

vercel deploy [caminho] -y --no-wait --scope <slug-da-equipe>

Se o projeto já estiver vinculado (.vercel/project.json ou .vercel/repo.json existir), o orgId nesses arquivos determina a equipe — não precisa perguntar novamente. Se houver apenas uma equipe (ou apenas uma conta pessoal), pule o prompt e use-a diretamente.

Sobre o diretório .vercel/: Um projeto vinculado tem:

.vercel/project.json — criado por vercel link (vinculação de projeto único). Contém projectId e orgId.
.vercel/repo.json — criado por vercel link --repo (vinculação baseada em repositório). Contém orgId, remoteName e um array projects mapeando diretórios para IDs de projetos Vercel.

Qualquer um dos arquivos significa que o projeto está vinculado. Verifique ambos.

NÃO use vercel project inspect, vercel ls ou vercel link para detectar o estado em um diretório não vinculado — sem uma configuração .vercel/, eles solicitarão interativamente (ou com --yes, vincularão silenciosamente como efeito colateral). Apenas vercel whoami é seguro de executar em qualquer lugar.

Etapa 2: Escolher um Método de Implantação

Vinculado (`.vercel/` existe) + tem repositório remoto git → Git Push

Este é o estado ideal. O projeto está vinculado e tem integração git.

Pergunte ao usuário antes de enviar. Nunca envie sem aprovação explícita:

Este projeto está conectado à Vercel via git. Posso commitar e enviar para
acionar uma implantação. Deseja prosseguir?

Commite e envie:
```
git add .
git commit -m "deploy: <descrição das alterações>"
git push
```
A Vercel constrói automaticamente a partir do push. Branches não-produção recebem implantações de pré-visualização; o branch de produção (geralmente main) recebe uma implantação de produção.
Recupere o URL de pré-visualização. Se o CLI estiver autenticado:
```
sleep 5
vercel ls --format json
```
A saída JSON tem um array deployments. Encontre a entrada mais recente — seu campo url é o URL de pré-visualização.

Se o CLI não estiver autenticado, informe ao usuário para verificar o painel da Vercel ou as verificações de status no provedor git para o URL de pré-visualização.

Vinculado (`.vercel/` existe) + sem repositório remoto git → `vercel deploy`

O projeto está vinculado, mas não há repositório git. Implante diretamente com o CLI.

vercel deploy [caminho] -y --no-wait

Use --no-wait para que o CLI retorne imediatamente com o URL de implantação em vez de bloquear até o build terminar (builds podem demorar). Depois, verifique o status da implantação com:

vercel inspect <url-da-implantação>

Para implantações de produção (apenas se o usuário solicitar explicitamente):

vercel deploy [caminho] --prod -y --no-wait

Não vinculado + CLI autenticado → Vincular primeiro, depois implantar

O CLI está funcionando, mas o projeto ainda não está vinculado. Esta é a oportunidade de colocar o usuário no melhor estado.

Pergunte ao usuário em qual equipe implantar. Apresente os slugs de equipe da Etapa 1 como uma lista com marcadores. Se houver apenas uma equipe (ou apenas uma conta pessoal), pule esta etapa.

Assim que uma equipe for selecionada, prossiga diretamente para a vinculação. Informe ao usuário o que acontecerá, mas não peça confirmação separada:

Vinculando este projeto a <nome-da-equipe> na Vercel. Isso criará um projeto
Vercel para implantar e habilitará implantações automáticas em futuros pushes git.

Se existir um repositório remoto git, use a vinculação baseada em repositório com o escopo da equipe selecionada:
```
vercel link --repo --scope <slug-da-equipe>
```
Isso lê o URL do repositório remoto git e o combina com projetos Vercel existentes que implantam a partir desse repositório. Cria .vercel/repo.json. Isso é muito mais confiável do que vercel link (sem --repo), que tenta combinar pelo nome do diretório e frequentemente falha quando a pasta local e o projeto Vercel têm nomes diferentes.

Se não houver repositório remoto git, recorra à vinculação padrão:
```
vercel link --scope <slug-da-equipe>
```
Isso solicita que o usuário selecione ou crie um projeto. Cria .vercel/project.json.
Depois, implante usando o melhor método disponível:
- Se existir um repositório remoto git → commit e push (veja método git push acima)
- Se não houver repositório remoto git → vercel deploy [caminho] -y --no-wait --scope <slug-da-equipe>, depois vercel inspect <url> para verificar o status

Não vinculado + CLI não autenticado → Instalar, autenticar, vincular, implantar

O CLI da Vercel não está configurado.

Instale o CLI (se ainda não estiver instalado):
```
npm install -g vercel
```
Autentique:
```
vercel login
```
O usuário completa a autenticação no navegador. Se estiver em um ambiente não interativo onde o login não é possível, pule para o fallback sem autenticação abaixo.
Pergunte em qual equipe implantar — apresente os slugs de equipe de vercel teams list --format json como uma lista com marcadores. Se apenas uma equipe / conta pessoal, pule. Após selecionada, prossiga imediatamente.

Vincule o projeto com o escopo da equipe selecionada (use --repo se existir um repositório remoto git, vercel link simples caso contrário):

vercel link --repo --scope <slug-da-equipe>   # se existir repositório remoto git
vercel link --scope <slug-da-equipe>          # se não houver repositório remoto git

Implante usando o melhor método disponível (git push se existir repositório remoto, caso contrário vercel deploy -y --no-wait --scope <slug-da-equipe>, depois vercel inspect <url> para verificar o status).

Fallback sem Autenticação — sandbox do claude.ai

Quando usar: Último recurso quando o CLI não puder ser instalado ou autenticado no sandbox do claude.ai. Isso não requer autenticação — retorna um URL de Pré-visualização (site ao vivo) e um URL de Reivindicação (transferência para sua conta Vercel).

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [caminho]

Argumentos:

caminho - Diretório para implantar, ou um arquivo .tgz (padrão: diretório atual)

Exemplos:

# Implantar diretório atual
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh

# Implantar projeto específico
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /caminho/para/projeto

# Implantar tarball existente
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /caminho/para/projeto.tgz

O script detecta automaticamente o framework a partir de package.json, empacota o projeto (excluindo node_modules, .git, .env), o envia e aguarda a conclusão do build.

Informe ao usuário: "Sua implantação está pronta em [previewUrl]. Reivindique-a em [claimUrl] para gerenciar sua implantação."

Fallback sem Autenticação — sandbox do Codex

Quando usar: No sandbox do Codex onde o CLI pode não estar autenticado. O Codex executa em um ambiente em sandbox por padrão — tente o CLI primeiro e recorra ao script de implantação se a autenticação falhar.

Verifique se o CLI da Vercel está instalado (nenhuma escalação necessária para esta verificação):
```
command -v vercel
```
Se vercel estiver instalado, tente implantar com o CLI:
```
vercel deploy [caminho] -y --no-wait
```

Se vercel não estiver instalado, ou o CLI falhar com "Nenhuma credencial existente encontrada", use o script de fallback:

diretorio_skill="<caminho-para-skill>"

# Implantar diretório atual
bash "$diretorio_skill/resources/deploy-codex.sh"

# Implantar projeto específico
bash "$diretorio_skill/resources/deploy-codex.sh" /caminho/para/projeto

# Implantar tarball existente
bash "$diretorio_skill/resources/deploy-codex.sh" /caminho/para/projeto.tgz

O script lida com detecção de framework, empacotamento e implantação. Ele aguarda a conclusão do build e retorna JSON com previewUrl e claimUrl.

Informe ao usuário: "Sua implantação está pronta em [previewUrl]. Reivindique-a em [claimUrl] para gerenciar sua implantação."

Acesso de rede escalado: Escalone apenas o comando de implantação real se o sandbox bloquear a chamada de rede (sandbox_permissions=require_escalated). Não escale a verificação command -v vercel.

Notas Específicas do Agente

Claude Code / agentes baseados em terminal

Você tem acesso total ao shell. NÃO use o caminho /mnt/skills/. Siga o fluxo de decisão acima usando o CLI diretamente.

Para o fallback sem autenticação, execute o script de implantação do local de instalação da skill:

bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [caminho]

O caminho pode variar dependendo de onde o usuário instalou a skill.

Ambientes em sandbox (claude.ai)

Você provavelmente não pode executar vercel login ou git push. Vá diretamente para o fallback sem autenticação — sandbox do claude.ai.

Codex

O Codex executa em um sandbox. Verifique primeiro se o CLI está disponível, depois recorra ao script de implantação. Vá para o fallback sem autenticação — sandbox do Codex.

Saída

Sempre mostre ao usuário o URL de implantação.

Git push: Use vercel ls --format json para encontrar o URL de pré-visualização. Se o CLI não estiver autenticado, informe ao usuário para verificar o painel da Vercel ou as verificações de status do commit.
CLI deploy: Mostre o URL retornado por vercel deploy --no-wait. Use vercel inspect <url> para verificar o status do build e relatá-lo ao usuário.

Fallback sem autenticação: Mostre tanto o URL de pré-visualização quanto o URL de reivindicação:

Implantação bem-sucedida!

URL de Pré-visualização: https://my-app-abc123.vercel.app
URL de Reivindicação:   https://vercel.com/claim-deployment?code=...

Veja seu site no URL de Pré-visualização.
Para transferir esta implantação para sua conta Vercel, visite o URL de Reivindicação.

Não use curl ou fetch para verificar se o URL implantado funciona. Apenas retorne o link.

Solução de Problemas

Erro de Egresso de Rede (claude.ai)

Se a implantação falhar devido a restrições de rede no claude.ai, informe ao usuário:

Falha na implantação devido a restrições de rede. Para corrigir:

1. Vá para https://claude.ai/settings/capabilities
2. Adicione *.vercel.com aos domínios permitidos
3. Tente implantar novamente

Acesso de Rede Escalado (Codex / ambientes em sandbox)

Se a implantação falhar devido a problemas de rede (timeouts, erros de DNS, conexões redefinidas) em um ambiente em sandbox, execute novamente com permissões escaladas (sandbox_permissions=require_escalated). Não escale a verificação inicial de disponibilidade do CLI — escale apenas o comando de implantação real.

Exemplo de orientação ao usuário:

A implantação precisa de acesso de rede escalado para implantar na Vercel. Posso executar
novamente o comando com permissões escaladas — deseja prosseguir?

Falha de Autenticação do CLI

Se vercel login ou vercel deploy falhar com erros de autenticação, recorra ao script de implantação sem autenticação (variante claude.ai ou Codex, dependendo do ambiente).

PhuongDeveloper/landingpage

O que é landingpage?

Perguntar na sua IA favorita

Documentação