socai-io/socai

Implantação do site da socai

Use esta skill sempre que a tarefa envolver a implantação do site da socai, configuração do Vercel, socai.io, www.socai.io, /download, /github ou implantações de pré-visualização de PR.

Esta skill é o runbook de implantação fonte da verdade. ../../../docs/website-deployment.md intencionalmente permanece breve e aponta para cá para evitar instruções duplicadas e divergentes.

Contexto do projeto

• Código-fonte do site: site/
• Framework: Site estático Astro
• Time/escopo Vercel: socai-d83824c8 (socai)
• Projeto Vercel: socai-site
• Domínio de produção: https://socai.io
• Rota de documentação: https://socai.io/docs/ (páginas Starlight construídas com o site Astro)
• Host canônico: socai.io
• Comportamento www: https://www.socai.io/* deve redirecionar (308) para https://socai.io/*
• Rota de download: https://socai.io/download redireciona para o DMG macOS universal mais recente no mirror de lançamentos OSS da socai
• Rota GitHub: https://socai.io/github redireciona para https://github.com/socai-io/socai

Configurações esperadas do projeto Vercel:

Configuração	Valor
Preset do framework	Astro
Diretório raiz	site
Comando de instalação	pnpm install
Comando de build	pnpm build
Diretório de saída	dist
Versão do Node.js	24.x

Regras de segurança

• Use o escopo socai-d83824c8 para todos os comandos de projeto/domínio Vercel.
• Não implante de um time Vercel errado ou de um projeto pessoal.
• Não comite site/.vercel/, site/dist/, site/.astro/ ou site/node_modules/.
• Não ative analytics a menos que o usuário aprove explicitamente.
• Não edite assets de lançamento do aplicativo enquanto trabalha na implantação do site.
• Mantenha o trabalho de issues em um branch dedicado e abra/atualize um PR para alterações no repositório.
• Se você alterar temporariamente as configurações do projeto Vercel para uma implantação manual, restaure-as antes de finalizar.

Validação local

Antes de implantar ou abrir um PR para código/config relacionado à implantação:

cd site
pnpm install
pnpm build

Valide a configuração JSON/XML quando modificada:

python3 -m json.tool site/vercel.json >/dev/null
python3 -m json.tool site/public/site.webmanifest >/dev/null
python3 - <<'PY'
import xml.etree.ElementTree as ET
ET.parse('site/dist/sitemap-index.xml')
ET.parse('site/dist/sitemap-0.xml')
PY

Inspecionar estado do Vercel

vercel whoami
vercel teams ls
vercel projects ls --scope socai-d83824c8
vercel project inspect socai-site --scope socai-d83824c8 --yes
vercel domains inspect socai.io --scope socai-d83824c8
vercel domains inspect www.socai.io --scope socai-d83824c8

Confirme que as configurações do projeto mostram diretório raiz site, framework Astro, comando de build pnpm build, saída dist, instalação pnpm install.

Implantação de produção preferida

Caminho preferido após a integração Git estar habilitada:

1. Mescle as alterações do site para main.
2. Deixe o Vercel construir o projeto socai-site a partir do diretório raiz site.
3. Verifique as URLs de produção com os comandos abaixo.

Pré-visualizações de PR também exigem que a integração Git esteja conectada no dashboard do Vercel.

Implantação de produção de emergência/manual via CLI

Como o projeto Vercel está configurado com diretório raiz site, uma implantação local direta a partir de site/ pode falhar com erros de diretório raiz site/site. Se a integração Git não estiver disponível e uma implantação via CLI for necessária, use este workaround de raiz temporária e restaure o diretório raiz após.

set -euo pipefail

cat > /tmp/vercel-root-null.json <<'EOF'
{
  "rootDirectory": null
}
EOF
cat > /tmp/vercel-root-site.json <<'EOF'
{
  "rootDirectory": "site"
}
EOF

restore_root() {
  vercel api /v10/projects/socai-site \
    --scope socai-d83824c8 \
    -X PATCH \
    --input /tmp/vercel-root-site.json \
    --silent || true
}
trap restore_root EXIT

vercel api /v10/projects/socai-site \
  --scope socai-d83824c8 \
  -X PATCH \
  --input /tmp/vercel-root-null.json \
  --silent

cd site
vercel deploy --prod --scope socai-d83824c8 --project socai-site --yes

Após a implantação, confirme que o diretório raiz foi restaurado:

vercel project inspect socai-site --scope socai-d83824c8 --yes

Não deixe o projeto com Diretório Raiz . ou null; as pré-visualizações Git dependem de site.

Verificação de URLs

Use verificações HEAD primeiro:

curl -I https://socai.io/
curl -I https://socai.io/docs/
curl -I https://socai.io/docs/quickstart/
curl -I https://www.socai.io/
curl -I https://socai.io/sitemap.xml
curl -I https://socai.io/sitemap-index.xml
curl -I https://socai.io/download
curl -I https://socai.io/github

Comportamento esperado no primeiro salto:

• https://socai.io/ retorna 200.
• https://socai.io/docs/ retorna 200, e uma página aninhada como /docs/quickstart/ retorna 200.
• https://www.socai.io/ retorna 308 com location: https://socai.io/.
• https://socai.io/sitemap.xml redireciona permanentemente para /sitemap-index.xml, que retorna 200.
• https://socai.io/download retorna um redirecionamento Vercel (307) para o DMG macOS universal mais recente no mirror de lançamentos OSS configurado.
• https://socai.io/github retorna um redirecionamento Vercel (307) para https://github.com/socai-io/socai.

Use -L apenas quando quiser seguir a cadeia:

curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/download

Configuração de pré-visualização Git

Tente:

cd site
vercel link --yes --scope socai-d83824c8 --project socai-site
vercel git connect https://github.com/socai-io/socai --scope socai-d83824c8

Se o Vercel retornar:

Failed to link socai-io/socai. You need to add a Login Connection to your GitHub account first.

então um proprietário da conta Vercel/GitHub deve conectar o login/integração do GitHub no dashboard do Vercel, depois conectar socai-site a socai-io/socai com diretório raiz site.

Solução de problemas

Alterações no site ignoradas após um push com múltiplos commits

A etapa de build ignorada em site/vercel.json deve comparar HEAD com VERCEL_GIT_PREVIOUS_SHA (o último deploy bem-sucedido para este projeto e branch), não HEAD^. O commit final em um push pode alterar apenas código Rust enquanto commits anteriores alteram o site. Se o SHA do deploy anterior estiver ausente ou indisponível no clone raso, construa em vez de pular. Exit 0 pula um build; exit 1 prossegue.

O diretório raiz "site" não existe

Isso geralmente acontece ao executar deploy CLI local de site/ enquanto o projeto remoto também tem o diretório raiz site. Use o workaround de implantação de emergência/manual CLI acima, ou prefira implantações Git.

Muitos arquivos enviados

Implantar a partir da raiz do repositório pode incluir artefatos de build Rust/Python e exceder o limite de arquivos do Vercel. Não implante a raiz do repositório diretamente a menos que você tenha uma estratégia testada de ignorar/arquivar. Prefira implantações Git ou o deploy de emergência/manual de site/ com reset temporário da raiz.

www.socai.io serve 200 em vez de redirecionar

Certifique-se de que o último deploy de produção inclua o redirecionamento de host em site/vercel.json, depois reimplante. Verifique com:

curl -I https://www.socai.io/

Metadados da última versão do GitHub não estão disponíveis

O site ainda deve mostrar uma cópia genérica não desatualizada (última versão) e /download ainda deve redirecionar para o asset da última versão do GitHub.

Reportando de volta

Ao relatar uma tarefa de implantação, inclua:

• Branch/PR se os arquivos do repositório foram alterados
• Configurações do projeto Vercel confirmadas
• URL de implantação e domínio de produção
• Comandos executados
• Resumo da saída de verificação para /, /docs/, /docs/quickstart/, www, /download e /github
• Quaisquer bloqueios manuais restantes, especialmente integração Git / pré-visualizações de PR