BennyKok/omg.dev

Construir e entregar um aplicativo omg.dev

Transforme a descrição do produto do usuário em um resultado funcional e verificado. Mantenha o trabalho de configuração com o agente. Pergunte apenas sobre escolhas de produto que alterem materialmente o resultado.

Faça uma pergunta por chamada de pergunta e coloque no máximo uma decisão nela. Uma segunda pergunta na mesma chamada não é mostrada ao usuário em todos os clientes. Se o usuário não disse o que o aplicativo deve fazer, pergunte isso em palavras simples e aguarde a resposta. Não construa um produto placeholder em seu lugar. Se uma pergunta expirar, pergunte novamente uma vez em uma mensagem normal e encerre a vez.

Estabelecer o projeto

• No Quick Chat, chame omg_create_project uma vez com um nome curto e descritivo. Defina template como expo para um aplicativo Expo ou móvel universal. O template Expo já contém um fluxo de tarefas funcional com dados armazenados no telefone, Expo Router, Liquid Glass, ícones Lucide, suporte web e configuração EAS. Use o repo.cwd retornado para cada comando, edição, verificação e implantação. Inspecione omg_list_repos antes de tentar novamente uma chamada de criação incerta.
• Em uma sessão New Project, o diretório atual já é o projeto. Ele contém Git, um README e esta habilidade. Não crie um segundo projeto.
• Preserve .git. Não sobrescreva uma pasta existente nem mova o Quick Chat atual para o novo projeto.

Escolher o caminho de entrega

• Para um site, aplicativo web ou API, use o runtime suportado do omg.dev, a menos que o usuário solicite outra plataforma. Em um projeto em branco, escaffolde o template React oficial do omg.dev antes de escrever código do produto. O diretório atual já contém Git e instruções do omg.dev, então gere em um diretório temporário dentro dele, copie o scaffold para o projeto e remova apenas esse diretório temporário:

  scaffold="$(mktemp -d .omg-web-scaffold-XXXXXX)"
  bunx --bun create-omg@latest "$scaffold" --template react-ts --no-install
  cp -a "$scaffold"/. .
  rm -rf "$scaffold"
  bun install
  

  Este template fornece @omg-dev/vite-plugin, vibes-build, funções de servidor, suporte a banco de dados e análise. Não substitua por create-vite ou um scaffold Vite escrito à mão. Leia https://docs.omg.dev/llms.txt e apenas as partes relevantes de https://docs.omg.dev/llms-full.txt antes de escolher pacotes adicionais ou contratos de API.

• Para um jogo (corrida, arcade, puzzle, aprendizagem infantil, palavras, 3D), crie o projeto com template: "web-game" e leia .agents/skills/omg-web-game-builder/SKILL.md em vez de projetar um motor. Seu passo 1 vem antes de qualquer edição de código: bun run dev em segundo plano na porta 5174, então omg_expose_port com porta 5174 e sem expoGo, depois informe ao usuário que a pré-visualização está pronta no card abaixo. As etapas de pré-visualização Expo nesta habilidade (porta 8081, expoGo: true) não se aplicam a um jogo web. Use template: "expo-game" e .agents/skills/omg-game-builder/SKILL.md apenas quando o usuário pedir um jogo para instalar no iPhone ou Android, ou nomear Expo ou um aplicativo nativo.

• Para um aplicativo Expo, comece a partir do template gerenciado expo e siga "Aplicativo Expo: o caminho rápido" abaixo. Adapte suas telas e seu armazenamento de dados em vez de reconstruir a configuração. Mantenha segredos em rotas de servidor hospedadas. Uma construção nativa de produção precisa que qualquer servidor seja implantado em uma origem segura; não trate um túnel sandbox como hospedagem de produção.

• Use um servidor Metro ativo para Expo Web e Expo Go em um Computador em Nuvem. Exponha sua porta através de omg_expose_port; não presuma que um CLI Expo global, Xcode, um simulador ou ferramentas específicas da máquina existam.

• Quando o aplicativo for compatível com Expo Go, omg_expose_port coloca o link exps:// do Expo Go em um card de pré-visualização no aplicativo omg.dev. Informe ao usuário que a pré-visualização está pronta e para abri-la no card abaixo. Não cole a URL exps:// bruta em sua resposta; o card já a mostra. Cole-a apenas onde o usuário não puder ver o card, como uma resposta enviada com omg_send_to_origin para um canal de mensagens, ou quando o usuário pedir o link. Não use túnel Expo, exposição LAN, exp.direct ou ngrok. Se o Expo Go não puder carregar um módulo nativo necessário, use uma construção de desenvolvimento quando autorizado ou relate esse limite claramente.

• TestFlight, envio para App Store, serviços pagos, domínios e contas de produção de terceiros são ações de entrega separadas. Faça-os apenas quando o usuário os solicitar e a conta necessária estiver disponível. TestFlight precisa da conta Expo do usuário e de uma conta paga de desenvolvedor Apple, mas uma construção em nuvem EAS não precisa de Xcode ou um Mac no sandbox. Use fluxos de login suportados e nunca peça senhas ou tokens no chat.

Aplicativo Expo: o caminho rápido

Um novo usuário está esperando. A primeira tela deve chegar ao telefone dele em cerca de 3 minutos, antes de qualquer trabalho de funcionalidade. Siga estas etapas em ordem:

1. omg_create_project com template: "expo". Se node_modules estiver faltando, execute bun install uma vez.
2. Pré-visualize antes de escrever qualquer código. Chame omg_expose_port com porta 8081 e expoGo: true. Em seguida, execute bash scripts/start-expo-preview.sh <expoGo.proxyUrl> 8081 a partir do diretório do projeto, com um timeout de shell de 240000 ms. Quando imprimir Sandbox proxy answers: HTTP 200, apresente primeiro a pré-visualização web: "Seu aplicativo está pronto. O card abaixo mostra ele funcionando, e funciona em qualquer dispositivo." Em seguida, mencione o telefone em uma frase: "Para experimentar no seu próprio telefone, toque em Seu telefone no card." Quando o resultado de omg_expose_port tiver simulatorAvailable: true, adicione mais uma frase: "Você também pode experimentar em um iPhone diretamente no card: toque em Simulador." Não prometa o simulador quando esse campo for falso ou estiver ausente. Não cole expoGo.url; o card a mostra. O Metro recarrega o aplicativo em cada salvamento, então a pré-visualização segue suas edições daqui em diante.
3. Escreva as telas, em algumas edições maiores em vez de uma pequena edição por turno. Substitua a tela inicial do template em src/app/index.tsx; não adicione uma segunda rota de índice.
4. Execute bun run typecheck e corrija o que ele relatar. Ele também verifica as rotas e falha em uma segunda tela inicial ou uma pasta app/ raiz. Em seguida, execute bun run check:ui, abra seus PNGs e corrija o que estiver errado (consulte a Etapa de Build 4). Não escreva testes automatizados a menos que o usuário peça.
5. Implante uma vez com omg_deploy (veja abaixo). Os dados permanecem no telefone, então esta é uma construção web estática.
6. Finalize com omg_ship.

Não navegue em node_modules, busque documentação ou leia o template arquivo por arquivo antes da primeira pré-visualização: o resumo abaixo é suficiente. Não escreva seus próprios loops de teste de navegador ou scripts de captura de tela: bun run check:ui faz isso. Se você não puder visualizar imagens, leia apenas seu relatório de texto.

O template:

• src/app/index.tsx: a tela inicial e o único arquivo para /. Substitua seu conteúdo pela sua tela inicial. Mantenha cada tela em src/app/: o Expo Router ignora uma pasta app/ raiz enquanto src/app existir. Para abas, mova a tela inicial para src/app/(tabs)/index.tsx e exclua src/app/index.tsx, porque ambos respondem a / e o antigo vence. O arquivo do template tem um cabeçalho, uma entrada com um botão adicionar, uma lista com alternar e excluir, um card de erro e um botão recarregar. Os estilos estão em um StyleSheet no final; as constantes de tema estão no topo (INK, CORAL, BACKGROUND, SURFACE, SURFACE_BORDER).
• src/app/_layout.tsx: uma pilha do Expo Router sem cabeçalho, dentro de KeyboardProvider. Uma nova tela é um novo arquivo em src/app/ (stats.tsx é /stats). Navegue com router.push("/stats") ou <Link href="/stats"> de expo-router.
• src/lib/tasks.ts: os dados, armazenados no telefone com AsyncStorage (localStorage na web). tasksApi.list(), create(title), update(id, patch), remove(id). Mantenha este arquivo. Para cada novo tipo de item, copie sua forma com sua própria chave de armazenamento.
• Ícones: lucide-react-native, por exemplo <Plus color={CORAL} size={22} />. Superfícies de vidro: GlassView de expo-glass-effect.
• Cores: defina cada constante de tema a partir do design antes de estilizar as telas. Cartões, linhas e folhas usam a cor de superfície do próprio design. O SURFACE branco translúcido do template serve apenas para seu starter claro; deixado em um design escuro ou colorido, cada cartão fica branco. Use GlassView apenas onde o design mostra vidro fosco. No Android, ele não desenha vidro, então dê a ele uma cor de fundo.
• Áreas seguras: envolva cada tela em SafeAreaView de react-native-safe-area-context com edges={["top", "bottom"]}, ou use useSafeAreaInsets(). Nunca importe SafeAreaView de react-native: é apenas iOS, então no Android o cabeçalho vai sob a barra de status e a barra de abas sob a barra de gestos.
• Teclado: coloque telas com uma entrada de texto em KeyboardAwareScrollView de src/lib/keyboard (bottomOffset={24}, keyboardShouldPersistTaps="handled"), como o template faz. Para um campo fixado na parte inferior, use KeyboardStickyView do mesmo arquivo. Importe-os de src/lib/keyboard, nunca de react-native-keyboard-controller diretamente: seu gêmeo .web.tsx mantém a exportação web estática funcionando. Não use KeyboardAvoidingView do React Native: no iOS a tela se move após o teclado, lentamente.

Dados: armazene-os no telefone por padrão, com o padrão tasks.ts. Use dados hospedados apenas quando o usuário pedir contas ou dados compartilhados entre pessoas. Em seguida, adicione login com @omg-dev/sdk e coleções .scoped("user") em schema.ts. Nunca chame /api/... com um fetch bruto: uma coleção hospedada responde a um telefone anônimo com 401 Authentication required.

Para dados hospedados, instale o @omg-dev/sdk mais recente e implante o backend antes de testar seus dados compartilhados no Metro. Mantenha .omg/project.json no diretório do projeto. A pré-visualização web hospedada usa essa identidade de aplicativo registrada e autentica seu proprietário através do SDK. Use <VibesAuthProvider> e requisições SDK. Não adicione um login de pré-visualização separado, encaminhe cookies de painel ou substitua as permissões do aplicativo do usuário. Um telefone físico ainda precisa do login normal do aplicativo e da origem do backend implantado.

Regras do Metro: use apenas portas 8081 a 8099, porque os links do Expo Go funcionam apenas nessa faixa. Inicie o Metro apenas com o script; npx e ss não estão instalados em todos os Computadores.

Blocos de construção (Expo)

O template vem com ajudantes testados em src/kit/. Importe-os; não os reescreva. Eles funcionam em iOS, Android e web. Cada arquivo começa com um comentário que mostra seu uso.

• overlay.tsx: useConfirm() e useSheet(). <OverlayProvider> já está em _layout.tsx. Use if (await confirm({ title, destructive: true })) para cada exclusão ou confirmação. Alert.alert com botões não faz nada na web. Use useSheet().open(node) para folhas e formulários. Não empilhe componentes Modal: o segundo desenha atrás do primeiro na web.
• ActionRow.tsx: uma linha pressionável com uma ação de excluir ou outra ao lado. Um botão aninhado dentro de uma linha pressionável também aciona a linha na web.
• image.ts: await toPersistentImage(pickerAsset). Chame o seletor com base64: true, quality: 0.5 e armazene a string retornada. Um URI do seletor na web é uma URL blob: que desaparece após um recarregamento.
• use-timer.ts: usePersistedTimer(key, durationMs) com start, pause, resume, reset e formatClock. Ele armazena o horário final, então um recarregamento não o redefine. Use para cada timer ou contagem regressiva.
• use-viewport.ts: useViewport() e useIsWide(). Na exportação web estática, useWindowDimensions() pode dar largura 0 na primeira renderização. Prefira flex e maxWidth; use o hook apenas quando precisar de um número.

Dados compartilhados entre pessoas (uma lista compartilhada, uma troca, um grupo): use o caminho do @omg-dev/sdk hospedado em "Dados" acima. Não escreva um servidor local. Se um servidor local for inevitável, responda OPTIONS e envie estes cabeçalhos em cada resposta: Access-Control-Allow-Origin com a Origin da requisição (ou *), Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS, e Access-Control-Allow-Headers: content-type,authorization. Um PUT ou DELETE ausente falha apenas no navegador.

Build

1. Converta a solicitação em uma pequena condição de conclusão observável. Faça escolhas visuais e técnicas razoáveis quando o usuário não as especificou.
2. Escaffolde dentro do diretório do projeto. Para um template Expo gerenciado, instale suas dependências fixadas e preserve .omg/template.json; não o substitua por outro starter. Para um projeto em branco, instale as dependências e configurações documentadas atuais. Não instale um CLI omg.dev descontinuado nem peça tokens de infraestrutura ao usuário; as ferramentas de runtime fornecem a credencial Cloud.
3. Implemente o caminho real. Se o produto precisar de dados compartilhados, autenticação, uploads ou trabalho de servidor, use as APIs hospedadas documentadas e verifique a persistência e o controle de acesso. Não substitua o comportamento compartilhado solicitado por dados mock ou armazenamento apenas no navegador.
4. Não escreva testes automatizados, a menos que o usuário os peça. Verifique com a autoverificação: execute bun run typecheck, depois bun run check:ui. O check constrói a exportação web, inicia o script server ou backend do aplicativo se houver um, abre cada rota em 390x844 e salva um PNG por rota em .omg/ui-check/. Ele relata páginas em branco, limites de erro, erros de console, requisições falhas, um servidor travado e botões ou links que outro elemento cobre (por exemplo, um botão "Adicionar" sob uma barra de abas). Em seguida, abra cada PNG com o visualizador de imagens e compare com a solicitação e quaisquer referências de design. Corrija o que estiver errado e execute o check novamente até que o relatório esteja limpo. Indique qual superfície você verificou; uma execução web não é prova de comportamento nativo.
5. Atualize o README com o propósito do produto, comando de execução local, arquitetura e notas de entrega. Commit o código-fonte finalizado localmente para que sessões posteriores do omg.dev comecem a partir de uma linha de base completa.

Login para aplicativo web hospedado

omg.dev possui o login para aplicativos em <slug>.omgs.app. Nunca construa um formulário de login, um campo de senha ou seu próprio armazenamento de sessão.

• Privado (padrão): cada visitante faz login no omg.dev antes que o aplicativo abra. O aplicativo não precisa de UI de login.
• Público com login: use quando o usuário quiser uma página de destino para visitantes. Defina o aplicativo como public com login obrigatório. Visitantes veem uma página pública (a rota / se nenhuma rota privada for especificada).

...

[truncado para tradução]