fayzfayz sdk

Testar e debugar

Antes de subir, você exercita o app sem infra e valida a estrutura com uma ferramenta. Três coisas fazem isso: o backend mock, o adapter de auth simulado e o fayz doctor.

O modo mock roda tudo sem banco

Um app recém-criado nasce com "backend": { "provider": "mock" }. Isso é dados de exemplo em memória — o app inteiro funciona sem Supabase, sem .env, sem rede. Cada plugin (e cada plugin seu, via createSafeDataProvider) traz um provider mock, então você desenvolve e demonstra a experiência completa antes de conectar qualquer coisa. Virar a chave para dados reais é trocar o provider no manifesto — veja Supabase.

O auth simulado

No mesmo espírito, o createMockAuthAdapter do @fayz-ai/auth entrega uma sessão logada como um usuário demo, persistida no navegador — sem tela de login, sem provedor. No caminho manifesto-primeiro, o adapter de auth segue o backend.provider: em mock, a auth é simulada automaticamente. Assim você testa telas que dependem de "estar logado" sem montar auth de verdade. O detalhe está em Auth — visão geral.

fayz doctor: a rede de segurança

O doctor valida o app parado — sem subir nada. Rode-o depois de qualquer mudança:

npx @fayz-ai/cli doctor

Ele checa três coisas:

  • Estrutura do manifesto e fronteiras arquiteturais — manifestVersion, campos obrigatórios e surface com scaffold. Um problema estrutural faz o doctor sair com erro (exit 1). Hoje o doctor valida a forma do manifesto e as fronteiras, não os valores de enums como theme.brand ou backend.provider — a validação desses valores está chegando (há um fix de SDK em PR).
  • Boundaries de arquitetura — imports de SDK de provedor direto (provider-import), imports fora da superfície suportada (off-surface-import), dependências fora da superfície. Reportados como avisos (soft enforcement — não falham o build).
  • Plugins referenciados — cada id do manifesto precisa resolver para uma factory @fayz-ai/plugin-* instalada e ligada no código gerado, mais cobertura de locale.

Uma saída típica de um app mock saudável:

⚠ manifest references plugin(s) [dashboard] — each id must resolve to an installed @fayz-ai/plugin-* factory wired in src/plugins.generated.ts or src/config/app.tsx

0 error(s), 1 warning(s)

Leia o resumo final: N error(s), M warning(s). Erros você conserta antes de seguir; avisos são visibilidade — o aviso sobre plugins referenciados é esperado em modo mock (o dashboard é resolvido pelo bundle da plataforma) e não é um problema. Um app código-primeiro (sem app.manifest.json) roda só as checagens de boundary e passa.

Planeje migrações sem tocar no banco

Para debugar a camada de dados, o db apply --dry-run imprime o plano ordenado sem nenhuma chamada de rede e sem ler o seu PAT — seguro de rodar sempre:

npx @fayz-ai/cli db apply --dry-run

É a forma de conferir o que seria aplicado (e em que ordem: spine → drizzle → seed → plugins → incubator) antes de aplicar de verdade.

Próximo: coloque o app no ar em Deploy estático.