prisma/prisma-compute

Prisma Compute

Guie agentes através da criação, implantação, operações e prontidão de deploy por framework de aplicações Prisma Compute.

Superfície da CLI do Prisma Compute

Use a CLI da Plataforma Prisma para fluxos de trabalho de aplicações Compute:

bunx @prisma/cli@latest app deploy --help
bunx @prisma/cli@latest app --help
bunx @prisma/cli@latest build logs --help
bunx create-prisma@latest --help

Use @prisma/cli@latest para implantação de aplicações Compute. Use create-prisma@latest para scaffolding de novos projetos.

Enviar Feedback e Reportar Problemas da CLI

A CLI tem um canal de feedback embutido. Use-o sempre que um comando falhar (UNEXPECTED_ERROR), uma falha persistir após troubleshooting, ou o usuário pedir para enviar feedback para a equipe Prisma:

bunx @prisma/cli@latest feedback "app deploy crashed: <primeira linha do erro>"
bunx @prisma/cli@latest feedback "amei o fluxo de deploy" --email [email protected]

A saída de crash aponta para isso por conta própria: envelopes de crash --json carregam o comando pré-preenchido exato como uma entrada recover em nextActions (execute-o literalmente), e a saída de crash legível para humanos termina com uma dica Conte-nos o que aconteceu:. O feedback é anônimo a menos que --email seja passado e anexa apenas a versão da CLI, versão do Node.js e plataforma/arquitetura do SO. Nunca inclua segredos, URLs de conexão ou dados do usuário na mensagem.

Ordem de Fonte da Verdade

Use evidências nesta ordem ao decidir o que editar ou executar:

1. Scripts e configuração gerados do projeto, especialmente prisma.compute.ts, compute:deploy, configuração do framework e package.json.
2. Saída de ajuda da CLI de create-prisma e @prisma/cli.
3. Código do pacote instalado localmente, artefatos gerados e definições de tipo.
4. Documentação oficial.

Quando Aplicar

Use este skill para:

• Criar uma nova aplicação que possa ser implantada no Prisma Compute
• Implantar uma aplicação TypeScript existente no Prisma Compute
• Criar ou atualizar uma config de deploy tipada prisma.compute.ts
• Decidir se um framework está pronto para o Compute
• Depurar create-prisma --deploy, compute:deploy ou app deploy
• Gerenciar logs de aplicações Compute, deploys, variáveis de ambiente e domínios, e listar branches da plataforma (branch list; não há comandos de criar/remover branch)
• Inspecionar logs de build do GitHub/Console e status de push-to-deploy do GitHub
• Executar deploys não interativos com autenticação via navegador, múltiplos workspaces armazenados ou service tokens do Prisma
• Alternar, selecionar, listar ou fazer logout de workspaces locais da Plataforma Prisma para @prisma/cli
• Enviar feedback sobre uma falha insolúvel da CLI Compute com @prisma/cli feedback
• Deploys programáticos com @prisma/compute-sdk ou integrações com a Management API

Árvore de Decisão

1. Implantação ou reimplantação de projeto existente: Leia references/app-deploy-cli.md.

2. Config Compute tipada, monorepos, alvos de deploy, raízes de aplicação ou defaults de build/env: Leia references/compute-config.md.

3. Trabalho de build/ runtime específico de framework: Leia references/frameworks.md.

4. Novo projeto a partir de um scaffold: Leia references/create-prisma.md.

5. Deploy programático, SDKs, APIs ou conceitos de baixo nível de App/Deployment: Leia references/sdk-api.md.

6. Falhas de build, auth, env, deploy ou runtime: Leia references/troubleshooting.md.

Regras por Prioridade

Prioridade	Categoria	Impacto	Prefixo
1	Verificação de comando	CRÍTICO	verify-
2	Autenticação e seleção de workspace	CRÍTICO	auth-
3	Prontidão do framework	CRÍTICO	framework-
4	Binding de host e porta do runtime	CRÍTICO	runtime-
5	Config Compute tipada	ALTA	config-
6	Configuração de branch, ambiente e banco de dados	ALTA	env-
7	Operações de deploy	ALTA	deploy-
8	Automação de SDK e API	MÉDIA	sdk-

Regras Rápidas

1. Verificação de Comando

• verify-help-first - Use a saída de ajuda da CLI para confirmar a sintaxe do comando durante o trabalho.
• verify-prisma-vs-platform-cli - Não assuma que prisma app deploy existe na CLI do ORM; verifique se a tarefa deve usar @prisma/cli.
• verify-generated-scripts - Prefira o script compute:deploy gerado quando um projeto já o possui.
• verify-public-url - Após um deploy real, solicite a URL pública do deploy ao invés de confiar em verificações locais ou de prontidão.
• verify-config-support - Trate prisma.compute.ts como a config Compute tipada; inspecione a config e os scripts gerados do projeto antes de editar ou implantar.
• verify-auth-workspace-support - Use os comandos @prisma/cli auth workspace para fluxos de listar/usar/fazer logout de workspaces locais.

2. Autenticação e Seleção de Workspace

• auth-source-precedence - Um PRISMA_SERVICE_TOKEN não vazio é a fonte de auth ativa para comandos, e workspaces OAuth locais são ignorados para execução. Se estiver definido mas vazio, a CLI deve falhar ao invés de recorrer ao OAuth armazenado.
• auth-multi-workspace - auth login pode armazenar sessões OAuth para múltiplos workspaces na mesma máquina. O ponteiro de workspace ativo seleciona qual concessão OAuth armazenada os comandos normais usam.
• auth-list-before-switch - Use auth workspace list --json para inspecionar sessões locais. Agentes devem preferir ids de workspace do JSON em vez de nomes porque nomes podem ser ambíguos.
• auth-switch-explicitly - Use auth workspace use <id-or-name> para alternância não interativa. Use auth workspace use sem argumento apenas para um seletor interativo ou quando exatamente um workspace OAuth local existe.
• auth-no-fallthrough - Se o workspace OAuth ativo estiver desconectado ou falhar ao atualizar, a CLI não deve cair silenciosamente em outro workspace em cache. Execute auth workspace use <id> para escolher o próximo workspace.
• auth-single-workspace-logout - Use auth workspace logout <id-or-name> ou auth logout --workspace <id-or-name> para remover uma sessão de workspace OAuth local. auth logout simples limpa todas as sessões de workspace OAuth local.
• auth-service-token-switching - Enquanto PRISMA_SERVICE_TOKEN estiver definido, auth workspace use fica indisponível porque o service token é a fonte de auth ativa; desdefina a env var para alternar workspaces OAuth locais. Logout de workspace ainda limpa apenas o estado OAuth local.
• auth-storage-awareness - Credenciais OAuth locais residem no arquivo de auth da plataforma, com metadados do workspace em um arquivo de contexto sidecar. Pins de projeto residem em .prisma/local.json, e o estado de app/projeto da CLI reside em .prisma/cli/state.json próximo a prisma.compute.ts quando presente.

3. Prontidão do Framework

• framework-cli-first - Avalie a prontidão de deploy contra @prisma/cli app deploy, não contra o que create-prisma pode scaffoldar.
• framework-supported-cli-deploy - O deploy Compute suporta nextjs, nuxt, astro, hono, nestjs, tanstack-start, custom e bun.
• framework-create-prisma-defaults-only - create-prisma pode fornecer defaults gerados e compute:deploy, mas não é a superfície geral de deploy para apps existentes.
• framework-build-output - O Compute precisa de um entrypoint de servidor ou artefato do framework, não apenas saída estática.

4. Binding de Host e Porta do Runtime

• runtime-bind-all-interfaces - Servidores implantados devem fazer bind em todas as interfaces (0.0.0.0 ou o equivalente do framework), não localhost ou 127.0.0.1 fixados em código.
• runtime-match-http-port - A app deve escutar na porta HTTP implantada: leia process.env.PORT quando possível, ou passe o --http-port correspondente.
• runtime-readiness-port-only - A verificação de prontidão do Compute observa portas de escuta; um listener apenas em loopback pode parecer pronto enquanto o ingress público não consegue alcançá-lo.
• runtime-respond-within-60s - O ingress dá 60 segundos para a app começar a responder, depois retorna 504 Gateway Time-out e cancela a requisição. Projete handlers para responder primeiro e executar trabalhos mais longos sob waitUntil ou a partir de uma fila, nunca dentro da requisição.

5. Config Compute Tipada

• config-optional-simple-app - prisma.compute.ts não é necessário para implantar uma app simples normal; use flags quando não houver uma config durável.
• config-init-formalizer - Gere uma nova config com bunx @prisma/cli@latest init: ele detecta o framework, fixa nome/framework/httpPort (mais entry para Bun/Hono) e oferece o link do Projeto. --format json escreve um prisma.compute.json sem dependências. init recusa quando qualquer config já existe, nunca scaffolda código e nunca implanta.
• config-use-prisma-compute-ts - Coloque defaults de deploy reutilizáveis em prisma.compute.ts com defineComputeConfig, não em prisma.config.ts.
• config-app-vs-apps - Use app para um único alvo de deploy e apps para monorepos ou repositórios com múltiplas apps; defina exatamente um.
• config-monorepo-roots - Para monorepos, use prisma.compute.ts para declarar alvos de app, raízes, defaults de framework, entrypoints, portas e entradas de env.
• config-targets - Em configs de múltiplas apps, @prisma/cli app deploy web seleciona o alvo apps.web. Sem [app], comandos podem inferir o alvo do diretório atual; caso contrário, deploy pode executar todos os alvos enquanto build/run exigem um.
• config-region-new-app-only - Uma region de config é apenas um default para apps recém-criadas; deploys para apps existentes mantêm a região atual da app.
• config-custom-artifact - Use framework: "custom" com build.outputDirectory e build.entrypoint para artefatos pré-construídos ou customizados.
• config-no-project-branch-secrets - Não faça commit de Workspace, Project, Branch, intenção de produção, service tokens ou valores secretos em prisma.compute.ts; mantenha-os em flags, .prisma/local.json, armazenamento de env ou segredos de CI. Defaults no nível da app como region, root, framework, entry, httpPort e caminhos de arquivo env não secretos pertencem à config.
• config-flags-win - Flags explícitas de deploy como --framework, --entry, --http-port, --region e --env sobrescrevem valores de config correspondentes.

6. Branch, Ambiente e Banco de Dados

• env-do-not-leak-secrets - Nunca imprima DATABASE_URL completo, service tokens ou valores secretos.
• env-deploy-loads-dotenv - Scripts de deploy gerados podem carregar env via prisma.compute.ts ou --env .env; inspecione o script/config real antes de reimplantar.
• env-migrations-separate - Scripts de reimplantação não executam migrations ou dados de seed. Execute os scripts de banco de dados Prisma apropriados separadamente.
• env-cli-token-name - @prisma/cli usa PRISMA_SERVICE_TOKEN para autenticação via service token.
• env-branch-scope - Deploys de branch, env vars de branch e bancos de dados de branch devem usar o mesmo nome de branch; passe --branch <nome-git> explicitamente ao mirar uma branch de preview.
• env-production-vs-preview - Use --role production para ambiente de produção, --role preview para ambiente de template de preview e --branch <nome-git> para sobrescritas específicas da branch.
• env-db-explicit - Mantenha a fiação de banco de dados e env explícita através de comandos de banco de dados e env do projeto; exemplos de deploy não devem adicionar configuração de banco de dados, e deploys não executam migrations, dados de seed ou criam um banco de dados por app automaticamente.

7. Operações de Deploy

• deploy-prod-intent - Use --prod --yes apenas quando o usuário pretender um deploy de produção. O primeiro deploy de produção de uma App promove automaticamente sem --prod; a flag controla deploys subsequentes para a branch de produção.
• deploy-no-promote - Use app deploy --no-promote para build-then-verify: ele constrói um candidato acessível em sua própria URL sem tocar no deploy ativo, promovido depois com app promote <deployment-id>.
• deploy-github-default-branch - Quando uma app Compute está conectada ao push-to-deploy do GitHub, um merge na branch padrão é o caminho de deploy de produção; verifique registros de deploy ou verificações do GitHub em vez de dizer aos usuários para reimplantar a branch do PR mergeado ou executar um deploy de preview da branch padrão.
• deploy-build-logs - Use @prisma/cli build logs <build-id> para saída de build do GitHub/Console. Use app logs para logs de runtime do deploy; os dois ids são diferentes.
• deploy-noninteractive-auth - Deploys não interativos precisam ou do workspace OAuth ativo correto armazenado ou de uma env var de service token suportada; nunca imprima o token.
• deploy-json-for-agents - Use --json --no-interactive para scripts e saída legível para agentes.
• deploy-create-project - Use --create-project <nome> apenas quando o usuário quiser que o deploy crie e vincule um novo projeto; conflita com --project e PRISMA_PROJECT_ID.
• deploy-ops-targets - Comandos de app show/open/logs/list-deploys/promote/rollback/remove e domínio também podem aceitar alvos [app] de prisma.compute.ts.
• deploy-report-cli-bugs - Em UNEXPECTED_ERROR ou uma falha insolúvel, reporte-a com o comando de feedback; veja "Enviar Feedback e Reportar Problemas da CLI" acima.

8. SDK e API

• sdk-use-cli-first - Prefira @prisma/cli app deploy para fluxos de app; use create-prisma apenas para scaffoldar uma nova app, a menos que o usuário esteja construindo automação de baixo nível.
• sdk-result-handling - @prisma/compute-sdk retorna valores Result; verifique isOk()/isErr() em vez de confiar em exceções.
• sdk-snapshot-detection - Use detectComputeApp para snapshots de repositório que não estão checkados em disco; enumere workspaces você mesmo e chame-o uma vez por raiz candidata de app.

Fluxo de Trabalho Preferido

1. Inspecione o projeto: gerenciador de pacotes, template/framework, scripts de package.json, versão do Prisma, localização do Prisma Client, prisma.compute.ts e compute:deploy existente.
2. Verifique a saída de ajuda da CLI para o pacote realmente sendo usado.
3. Verifique o contexto de autenticação antes de mutações de projeto/app: auth whoami --json e, quando múltiplas sessões locais podem existir, auth workspace list --json.
4. Escolha o caminho:
   • deploy de app existente: alvo baseado em config quando presente, compute:deploy gerado ou flags @prisma/cli app build/run/deploy
   • scaffold de nova app: create-prisma, depois compute:deploy gerado ou @prisma/cli app deploy
   • automação de baixo nível: @prisma/compute-sdk ou Management API