Nota: O arquivo de estado
last-sync.jsoné criado automaticamente na primeira sincronização bem-sucedida. Ignore avisos de "arquivo ausente" na primeira execução.
Sincronização Automática de Portfólio
Sincroniza automaticamente repositórios do GitHub para seu site de portfólio.
Fluxo de Trabalho
Passo 1: Coletar configuração
Pergunte ao usuário:
- Nome de usuário do GitHub: (padrão do git config)
- Tipo de portfólio:
static(projects-data.js) ousupabase(API) - Diretório do portfólio: Caminho para o projeto do portfólio
- Filtros: Excluir repositórios (arquivados, forks, nomes específicos)
Passo 2: Buscar repositórios via API do GitHub
GET /users/{username}/repos?per_page=100&sort=updated&direction=desc
Extrair: name, description, html_url, homepage, language, topics, updated_at
Filtrar:
- Forks (a menos que o usuário opte por incluí-los)
- Repositórios de perfil (
{username}/{username}) - Repositórios arquivados
Passo 3: Detectar alterações
Comparar com last-sync.json (armazenado no diretório da skill).
- Novos repositórios: Não estão na última sincronização → processo completo
- Repositórios atualizados:
updated_atmudou → recapturar screenshot - Repositórios inalterados: Pular
Passo 4: Capturar screenshots
Para repositórios com homepage ou URL de implantação:
const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();
Salvar no diretório de screenshots do portfólio.
Passo 5: Atualizar dados do portfólio
Estático (projects-data.js)
{
title: '{repo.name}',
description: 'Gerado automaticamente: {description}',
tech: '{language},{topics}',
github_url: '{html_url}',
live_url: '{homepage || ""}',
featured: false
}
Supabase
const res = await fetch('https://your-site.com/api/projects', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
body: JSON.stringify(projectData)
});
Passo 6: Salvar estado da sincronização
{
"lastSync": "2026-05-12T18:30:00Z",
"repos": {
"example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
}
}
Passo 7: Relatar resultados
Sincronização concluída:
+ 2 novos (Cyberian, Image Enhancer)
+ 1 screenshot capturado
+ 1 atualizado (Portfolio)
- 0 erros
Notas
- Screenshots exigem Playwright + URL válida. Pular se não houver homepage.
- Nunca altere
featured: trueem projetos existentes — apenas o usuário pode promover. - Agende via cron/GitHub Actions para sincronização semanal.
Tratamento de Erros
| Causa | Correção |
|---|---|
| API do GitHub retorna 401 Não Autorizado | Sem token ou token expirado. Defina a variável de ambiente GITHUB_TOKEN. Gere um novo Personal Access Token em github.com/settings/tokens com escopo public_repo. |
| Limite de taxa da API do GitHub excedido (403) | Requisições não autenticadas são limitadas a 60/hora. Autenticadas: 5000/hora. Adicione token. Se já autenticado, aguarde a redefinição (verifique cabeçalho X-RateLimit-Reset). |
Repositório não possui campo homepage nem URL de implantação | Não é possível capturar screenshot. Marque o repositório como "sem prévia ao vivo" na saída. Use a URL do GitHub como fallback. |
| Navegador Playwright não inicia | Chromium não instalado. Execute npx playwright install chromium. Em servidor headless, adicione flag --no-sandbox: chromium.launch({ headless: true, args: ['--no-sandbox'] }). |
| URL do screenshot retorna 404 ou timeout após 15s | URL de implantação está desatualizada ou site fora do ar. Pule screenshot para este repositório. Registre a URL e o erro em um arquivo failed-screenshots.json para revisão manual. |
projects-data.js tem formatação personalizada que a geração automática pode quebrar | Uma inserção baseada em regex pode corromper código escrito à mão. Leia o arquivo primeiro para detectar estrutura não padrão. Se detectada, anexe um bloco de comentário com as novas entradas e peça ao usuário para mesclar manualmente. |
| Inserção na API do Supabase falha com restrição de chave estrangeira ou esquema | O esquema do portfólio pode diferir da forma do payload gerado automaticamente. Leia o esquema da tabela Supabase primeiro. Mapeie campos explicitamente (não use operador spread). Valide com um POST de teste que retorne 200 antes de confirmar. |
last-sync.json está corrompido ou editado manualmente | Analise como JSON em um try-catch. Em caso de falha, renomeie para last-sync.json.bak e inicie sincronização completa do zero. Avise o usuário que a detecção incremental foi perdida. |
Padrões da API do GitHub
Descoberta de Repositórios
import requests, os
headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
# Buscar todos os repositórios (paginado)
repos = []
page = 1
while True:
r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
batch = r.json()
if not batch: break
repos.extend(batch)
page += 1
# Filtrar: apenas não-fork, não-arquivados, com descrição
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]
Limitação de Taxa
- API do GitHub: 5.000 requisições/hora (autenticado). Verifique cabeçalho
X-RateLimit-Remaining. - Para repositórios com 500+: use requisições condicionais (
If-None-Matchcom ETag) - Durma 1s entre capturas de screenshot (evitar limite de taxa do GitHub em assets)
Padrão de Screenshot com Playwright
from playwright.sync_api import sync_playwright
def capture(url, output_path):
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page(viewport={"width": 1280, "height": 800})
page.goto(url, timeout=15000, wait_until="networkidle")
page.screenshot(path=output_path, full_page=False)
browser.close()
Recuperação de Erros
- Timeout no carregamento da página -> tente novamente uma vez, se ainda falhar, pule (marque na saída)
- Repositório privado -> pule (não é possível capturar screenshot sem autenticação)
- Página crasha -> capture estado de erro como screenshot
- Falha de DNS -> pule com mensagem de log
Estratégia de Cache
import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}
for repo in repos:
key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
if cache.get(repo['full_name']) == key:
continue # Pular: sem alterações desde a última sincronização
# ... capturar screenshot, atualizar entrada ...
cache[repo['full_name']] = key
json.dump(cache, open(cache_file, 'w'))
Lista de Verificação
- Token do GitHub tem escopos corretos (repo, read:user) antes de buscar repositórios
- Screenshot executa apenas para repositórios com URLs homepage válidas (verificação HEAD primeiro)
- Navegador Playwright fechado no bloco finally para evitar processos órfãos
- Personalizações existentes do portfólio preservadas antes de upsertar novas entradas
- Modo dry-run disponível para visualizar alterações sem executar
Fontes
- Documentação da REST API v3 do GitHub (docs.github.com/en/rest/repos/repos) — listagem, filtragem e paginação de repositórios
- Documentação do Playwright (playwright.dev/docs/api/class-playwright) — inicialização de navegador headless, screenshot e configuração de viewport
- Documentação do cliente JavaScript do Supabase (supabase.com/docs/reference/javascript) — inserção via API, upsert e padrões de autenticação
- Documentação do módulo
fsdo Node.js (nodejs.org/api/fs.html) — leitura/escrita de arquivos com rename atômico para segurança do estado de sincronização - Melhores práticas para Personal Access Tokens (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — escopos, expiração e armazenamento seguro
- Agendamento cron do GitHub Actions (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — padrão de automação de sincronização semanal
- "Automate the Boring Stuff with Python" de Al Sweigart (No Starch Press, 2ª Edição, 2019) — padrões de confiabilidade de automação aplicáveis a tarefas de automação JavaScript
Anti-Padrões
| Padrão | Problema | Correção |
|---|---|---|
| Sincronizar sem verificar personalizações existentes | Entradas geradas automaticamente podem sobrescrever descrições de projeto artesanais, flags de destaque ou ordenação personalizada definida pelo usuário. | Leia o arquivo de destino primeiro. Detecte estrutura não padrão. Para entradas com featured: true, preserve todos os campos. Apenas faça upsert de repositórios novos ou alterados. |
| Capturar screenshots para todo repositório indiscriminadamente | Repositórios sem demonstrações ao vivo desperdiçam tempo de inicialização do Playwright (~3s cada). Repositórios com URLs quebradas produzem screenshots de erro inúteis. | Pré-filtre: capture screenshots apenas de repositórios onde o campo homepage não está vazio e retorna 200 em uma requisição HEAD. |
| Executar sincronização em conexão medida ou lenta | Clonar ou capturar screenshots de dezenas de repositórios pode consumir largura de banda e tempo significativos. | Execute em lotes de 10. Adicione uma flag --dry-run que liste o que mudaria sem executar. |
| Usar anon key do Supabase em vez de service_role key para escritas | Anon key tem restrições de segurança em nível de linha que bloqueiam upserts. | Use service_role key com cuidado. Armazene em variável de ambiente, nunca no código. Adicione políticas RLS no nível de tabela para a função de sincronização. |
| Não limpar processos do Playwright após a sincronização | Cada chromium.launch() inicia um processo. Processos órfãos acumulam memória e podem exaurir recursos do sistema. | Sempre chame browser.close() em um bloco finally. Rastreie navegadores iniciados em um array e force fechamento em SIGINT/SIGTERM. |
| Hardcodar o caminho dos dados do portfólio em vez de ler da configuração | Caminhos mudam entre projetos. Um caminho hardcodado quebra no primeiro uso em uma máquina diferente. | Pergunte pelo diretório do portfólio no Passo 1. Derive o caminho de projects-data.js a partir dessa base. Armazene no estado de sincronização para reutilização. |