CrabBox

O que CrabBox faz?

• Prova remota deliberada: siga a política de prova. Prefira prova local limitada em um host qualificado e disponível. Trabalhos caros ou específicos de plataforma podem usar capacidade remota. Enfileirado: pare a alocação própria; use CI do PR ou um escopo local seguro e relate requisitos descobertos. Build necessário indisponível antes da publicação: use a política de prova de rascunho/CI da skill de teste.
• Nunca aguarde filas nem encadeie fallbacks de provedores.

Backends:

• blacksmith-testbox: fonte mantenedora confiável. CI preparado. tbx_....
• aws: CrabBox intermediado direto. PRs novos. Sincronização/ambiente/captura personalizados. cbx_....
• local-container: fallback Docker. Não é prova remota.
• ssh: host operador existente. macOS/Windows/WSL2.

Sempre reporte provedor, id, URL da execução, comando, resultado. Nunca chame Testbox de "AWS CrabBox."

Contrato de Repositório

• Resolva comandos de exemplo, bootstrap, imagem de contêiner, PR a partir de instruções do consumidor confiável. Nunca invente comandos nem copie a configuração de outro consumidor.
• Configuração específica do consumidor permanece fora da skill portátil. Veja definições de placeholder.

Autorização e Isolamento

• Criação, reutilização, limpeza, estado temporário, checkouts limpos necessários para a tarefa: pré-aprovados. Preserve branches existentes, checkouts, edições não relacionadas.
• Confiança na fonte, credenciais, acesso de produção, orçamento, publicação permanecem limites de autoridade. Estado isolado; nunca toque no Gateway do operador sem aprovação por tarefa.

Roteie Primeiro

• Preserve o provedor resolvido: Testbox para fonte confiável; AWS direto quando sua semântica for necessária; CI/AWS sem segredos para código não confiável. Nunca execute wrappers/configurações não confiáveis localmente nem hidrate um lease não confiável.
• Adquira quando o comando estiver pronto; reutilize o ID próprio; pare depois.
• Menor perfil comprovado. Maior: evidência de memória registrada ou benefício de custo total medido é necessário, não falha/atraso/timeout genérico. Não aumente contagens de workers para compensar.
• Dimensionamento do Testbox: --blacksmith-workflow, nunca --class/--type direto; alterações de perfil exigem novos leases.
• Rótulos de runner do Blacksmith solicitam um nível, não CPU ou RAM garantidos. O Blacksmith pode alocar máquinas menores dependendo da disponibilidade do serviço. Para testes sensíveis a recursos ou benchmarks, meça CPUs disponíveis, afinidade/cotas e RAM utilizável na máquina alocada. Dimensione workers e workloads a partir dessas medições. Registre o nível solicitado e os recursos observados separadamente. Não qualifique hardware ou desempenho apenas por rótulos.
• Tamanho, duração, falha de hidratação, capacidade nunca autorizam substituições de provedor; seleção explícita do usuário ou semântica de backend necessária o fazem.

Pré-voo

Raiz do repositório confiável: leia .crabbox.yaml, resolva binário instalado, inspecione provedor/comandos:

export CRABBOX="$(command -v crabbox)"
test -n "$CRABBOX"
"$CRABBOX" --version
"$CRABBOX" config show --json | jq '{provider, profile, target}'
"$CRABBOX" run --help

• Use instruções de instalação/wrapper confiáveis do consumidor.
• Prova de ciclo de vida e cancelamento de comando nativo Linux/WSL requer uma distribuição CrabBox completa correspondente, ou um manifesto de runtime verificado selecionado com CRABBOX_RUNTIME_ARTIFACTS. Corresponda os companheiros à fonte congelada e verifique que o manifesto vincula o controlador exato selecionado. Uma CLI de desenvolvimento sem um pacote de runtime usa supervisão SSH legada; --version sozinho não estabelece supervisão nativa. Verifique o pacote selecionado antes da alocação; não conte prova apenas de CLI como prova de ciclo de vida nativo. Siga as instruções de artefatos de runtime upstream.
• Reparos: verifique upstream; use checkout próprio e limpo da tarefa; preserve binário instalado + fonte não relacionada. Nunca confie em checkout irmão apenas pelo nome.

Tempo de Vida do Lease

• TTL conta a partir da criação, incluindo hidratação; timeout ocioso conta inatividade. O prazo mais cedo vence. Padrões: 30m cada, máximo de 4h. Substituições do proprietário/org podem permitir até 24h; use política efetiva e avisos de limite sanitizados, não durações solicitadas. O aperto da política também se aplica a leases ativos.
• --keep e stop: never não impedem expiração. Solicite TTL e ociosidade explícitos e limitados para leases diretos retidos. Heartbeat simples, configuração, sincronização, SSH e uso de desktop não estendem o TTL total; run solicita extensão automática limitada apenas enquanto um comando executa, dentro da política, orçamento e capacidade do provedor.
• Antes de trabalho longo dependente de fonte, inspecione o tempo de vida total restante. Se permitido, solicite um extend <id> --ttl <total-desejado> --json limitado; a extensão não redefine o ocioso. Resultados negados/sem orçamento/não suportados/não progressivos/inativos exigem um salto ou falha visível, nunca troca de provedor ou cadeias infinitas de leases. Provedores com criação fixa, como Daytona, precisam de TTL suficiente na alocação.
• Falha de atualização direta do convidado pode deixar um prazo de provedor mais longo com o prazo antigo na máquina. Mantenha o mesmo estado local e tente novamente o mesmo TTL total fixo apenas para reconciliar; não trate a extensão falha como proteção.
• Honre directLeases: deny e directLeaseAllow confiáveis. Um provedor negado requer a rota do coordenador configurada; nunca contorne com credenciais diretas. O Testbox mantém seus limites nativos de job e ociosidade; --ttl não estende um workflow delegado.
• list mostra leases ativos do coordenador; list --retained adiciona recursos terminais mantidos cuja limpeza não foi confirmada. Use inspect/stop de ID exato para recuperação. Mantenha reivindicações e estado de recuperação até que uma parada bloqueante confirme a conclusão.

Testbox Confiável

Provedor resolvido = Testbox (ou explicitamente solicitado): comandos o preservam. Adicione --provider blacksmith-testbox apenas para substituição explícita:

"$CRABBOX" run --timing-json -- CI=1 <comando-de-verificação>

Vários comandos: aqueça uma vez, salve o id, reutilize, pare.

"$CRABBOX" warmup --keep --timing-json
"$CRABBOX" run --id <tbx_id> --timing-json -- <comando-de-verificação>
"$CRABBOX" stop <tbx_id>

Regras:

• Um lease, um comando ativo. Sem sincronização/reivindicação durante a execução.
• Prefira bash -c; perfis de login podem mudar diretórios. No shell de execução, afirme checkout físico + fonte/patch esperados; HEAD sozinho ≠ prova de sincronização suja. Siga o contrato de shell de hidratação documentado do consumidor.
• Testbox nativo executa sua própria sincronização, inclusive execuções reutilizadas --id. Nunca confie em --no-sync para baseline remoto: Blacksmith não tem bypass nativo; versões lançadas do CrabBox podem ignorar silenciosamente a flag. Reexecução intencional inalterada ≠ exceção.
• --reclaim apenas para transferência deliberada de propriedade do caminho de checkout.
• Siga o recibo de alocação do consumidor para reutilização. Commits de fonte compatíveis podem reutilizar um lease quando tarefa, checkout físico, base, dependências, preparação e workflow/job/ref permanecerem inalterados. Mantenha a proveniência de alocação original. Recibo incompatível: pare; reaqueça. Nenhuma substituição de lease obsoleto.
• SHA bruto não confiável para warmup --ref; use branch/tag.
• blacksmith testbox list oculta estados. Use list --all ou status --id <tbx_id>.
• Status/stop do Testbox: --id. Nenhum status --json.
• Provedor delegado rejeita --fresh-pr, --full-resync, --script*, --env-helper, flags de captura/download.

Downloads de diretório Blacksmith

Downloads recursivos + barra final remota necessária: downloads de diretório.

AWS Não Confiável

• Checkout limpo de branch padrão confiável. Binário CrabBox confiável instalado.
• Novo lease por SHA de cabeça completo revisado. Sem role de instância, Tailscale, hidratação.
• Encaminhe apenas CI. Faça upload de bootstrap confiável junto com --fresh-pr.

cd <checkout-limpo-branch-padrão-confiável>
env -u CRABBOX_AWS_INSTANCE_PROFILE \
  "$CRABBOX" config show --json | \
  jq -e '.aws.instanceProfile == ""' >/dev/null

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  -u CRABBOX_TAILSCALE \
  -u CRABBOX_TAILSCALE_AUTH_KEY \
  -u CRABBOX_TAILSCALE_AUTH_KEY_ENV \
  -u CRABBOX_TAILSCALE_EXIT_NODE \
  -u CRABBOX_TAILSCALE_EXIT_NODE_ALLOW_LAN_ACCESS \
  -u CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE \
  -u CRABBOX_TAILSCALE_TAGS \
  "$CRABBOX" warmup \
  --provider aws --network public --tailscale=false \
  --tailscale-exit-node= \
  --tailscale-exit-node-allow-lan-access=false \
  --ttl 4h --idle-timeout 90m --keep --timing-json

"$CRABBOX" inspect --provider aws --id <cbx_id> --json | \
  jq -e '.network == "public" and .tailscale == null' >/dev/null

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  CRABBOX_ENV_ALLOW=CI \
  "$CRABBOX" run \
  --provider aws --id <cbx_id> \
  --fresh-pr <proprietário/repo#número> \
  --no-hydrate --timing-json \
  --script <script-bootstrap-confiável> -- \
  <sha_cabeça_completo_esperado> <comando-de-verificação>

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  "$CRABBOX" stop --provider aws <cbx_id>

• O bootstrap confiável deve provar que as credenciais IAM IMDSv2 retornam 404; verificar SHA; remover variáveis de injeção de runtime; fixar toolchain; isolar HOME antes de instalar/testar.
• Cabeça alterada: novo lease. PR remoto ausente ou sem prova de role: fork CI sem segredos.

AWS Direta

• Comandos AWS confiáveis, diagnóstico de auth, ressincronização, execuções limpas de PR/contêiner: leia provedores diretos.
• Preserve --no-hydrate em execuções de contêiner; relate prova de contêiner local como local.

Observabilidade

• Coleta de artefatos/injeção de credenciais: leia flags de captura e ambiente.
• Chave exata, um comando. Nunca imprima segredos, escreva no repositório ou coloque no histórico do shell.
• Sem caminho de injeção seguro: auth ao vivo bloqueado; prova de chave falsa insuficiente.

E2E Real

• Exercite o ponto de entrada do usuário solicitado com estado isolado do consumidor, não apenas testes de unidade remotos.
• Para prova de instalação/provedor/interativa + comparação segura de revisão: leia procedimento E2E.

Desktop / Multiplataforma

Destinos SSH, pré-voo macOS pago, WebVNC, verificação de handoff de aplicativo: leia comandos desktop e multiplataforma.

Triage de Falhas

Identifique falha de wrapper, provedor, hidratação, sincronização, SSH ou comando:

"$CRABBOX" doctor
"$CRABBOX" status --id <id>
"$CRABBOX" inspect --id <id> --json
"$CRABBOX" logs <run_id>
"$CRABBOX" results <run_id>
blacksmith testbox list --all
blacksmith testbox status --id <tbx_id>

• Capacidade enfileirada: pare alocações próprias; siga a política de prova. Sem tempestade de tentativas ou troca de provedor.
• Sincronização obsoleta: --debug --timing-json, depois --full-resync uma vez em provedores diretos.
• Leia fase/JUnit com falha antes de execução focada novamente. Wrapper quebrado: diagnostique com CLI instalada no mesmo provedor; atualize através do caminho confiável do consumidor.
• Pare apenas IDs próprios; stop não aceita --timing-json.