swyxio/skills

Forge

O Forge tem duas superfícies sobre Cloudflare:

• Repositórios: Hospedagem Git, issues, pull requests, Actions, transcrições e agentes de repositório.
• Deploy / Sites: um SHA exato enviado vira uma pré-visualização e pode posteriormente se tornar a aplicação de produção.

Cloudflare continua sendo o runtime/provedor. Não substitua por outro Git ou produto de hospedagem quando Forge for o destino solicitado, e não presuma que uma aplicação hospedada herde a autenticação do Forge ou Cloudflare Access.

Mantenha a tarefa com escopo definido

Classifique o resultado solicitado antes de carregar mais processo:

• Operação de repositório: use Git comum mais autenticação do Forge.
• Implantação de aplicação do cliente: use Forge Deploy e seu registro de lançamento.
• Reparo de infraestrutura do Forge: use o menor caminho de lançamento saudável; o plano de controle sendo reparado não precisa implantar sua própria correção.
• Trabalho apenas com código-fonte, CLI, documentação, análise ou UI: não adicione portões de lançamento de produção, a menos que o usuário também tenha solicitado uma implantação.

Retenções locais de thread e lançamentos não relacionados não são pré-requisitos globais. Aplique apenas as verificações que mitigam um risco concreto na ação solicitada e pare quando esse resultado estiver comprovado. Registre descobertas não relacionadas como acompanhamentos.

Resolva o comportamento atual

O Forge está em evolução. Use o CLI instalado, o repositório alvo, a UI/API atual e apenas o código-fonte relevante de primeira parte roteado pelo Mapa de fontes do Forge. A documentação não comprova elegibilidade de conta atual, limites ou estado de lançamento.

Inspecione a sintaxe antes de construir comandos:

sf help
sf commands --json
sf schema --json
sf <comando> --help

Identifique a conta, o repositório, o branch padrão e, para Deploy, a raiz do projeto. Preserve um remote GitHub existente, a menos que o usuário peça para substituí-lo.

Autenticação de repositório

Um navegador logado no Forge não é uma credencial Git local. Use o fluxo de credencial com escopo do Forge sem expor seu token:

sf auth status
sf auth git-credential <dono>/<repo>
git ls-remote <forge-remote> HEAD

Mantenha credential.useHttpPath ativado. Nunca extraia tokens do armazenamento do navegador ou do chaveiro de outra aplicação, nem os coloque em remotes, código-fonte, histórico do shell ou saída. Não faça force-push, substitua origin, altere visibilidade ou amplie escopos de credencial sem a autorização necessária.

Para migração do GitHub, use o fluxo de importação atual do Forge. Preserve o gerenciador de pacotes e lide com Git LFS separadamente; importar histórico não copia objetos LFS hospedados.

Contrato do Forge Deploy

O Forge lança um SHA exato enviado, não o checkout local. Código-fonte, build, pré-visualização, publicação no provedor, ativação em produção e verificação ao vivo são estados distintos.

Cada projeto precisa de um forgeBuild.ts v1 apenas com dados em sua raiz configurada. Leia o manifesto atual a partir do mapa de fontes e, em seguida, valide:

npx smolforge deploy check

• Omitir build não executa nenhum comando de build do repositório.
• forgeBuild.ts é avaliado estaticamente; não use configuração executável, imports dinâmicos ou forge.yml/forge.yaml.
• Uma aplicação precisa de um entrypoint HTTP, assets, ou ambos. Use um fallback SPA apenas para roteamento do lado do navegador.
• .forge/config.json pode mapear projetos e propor bindings; ele não cria projetos, aplica estado do provedor nem concede autoridade de DNS.
• Bindings Wrangler importados podem expor recursos de produção a pré-visualizações.

Criar ou habilitar um projeto, aceitar termos de serviço, promoção, rollback, desabilitação, rotas e aplicar provedor são mudanças de estado externas separadas. URLs de pré-visualização são não listadas e noindex, não privadas; nunca coloque segredos ou dados privados nelas.

Lançamento e recuperação

Use Forge Deploy para aplicações do cliente. Para infraestrutura do Forge, prefira o caminho canônico enquanto ele estiver saudável e proporcional. Wrangler direto é um caminho de operador autorizado quando esse caminho estiver indisponível, não saudável, implicado no incidente ou obstruir materialmente o reparo delimitado; não é um atalho para contornar o registro de lançamento de uma aplicação do cliente.

Para um reparo direto de infraestrutura, escopo um componente exato, registre o SHA da fonte, versões atual e de rollback, e qualquer migração ou mudança de binding, depois verifique tráfego, saúde/dependências e uma reprodução. Não exija pré-visualizações não relacionadas, reconciliação de portfólio, prova exaustiva ou coordenação com tarefas que não possam modificar o mesmo componente ou esquema.

Antes de tentar novamente um lançamento bloqueado, identifique o último estado comprovado e o diagnóstico direcionado. Verifique o SHA exato, raiz do projeto, branch e configurações ativas de build/asset. Tente novamente apenas quando o alvo imutável e as condições de idempotência estiverem claros.

Referências

Use o Mapa de fontes do Forge para carregar apenas o documento de primeira parte que possui a questão atual.