From fb17882dadbeaebbcca03c651e236d2737d42f79 Mon Sep 17 00:00:00 2001 From: Esdras Renan Date: Wed, 5 Nov 2025 19:39:44 -0300 Subject: [PATCH] docs: atualizar instrucoes para bun e convex self-hosted --- README.md | 18 +++++++++--------- agents.md | 34 +++++++++++++++++----------------- docs/OPERACAO-PRODUCAO.md | 10 +++++----- docs/OPERATIONS.md | 6 +++--- scripts/deploy-from-git.sh | 3 +-- 5 files changed, 35 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 0ffc479..c87d82c 100644 --- a/README.md +++ b/README.md @@ -20,16 +20,16 @@ Aplicação **Next.js 16 (App Router)** com **React 19**, **Convex** e **Better - `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL` 3. Aplique as migrações e gere o client Prisma: ```bash - pnpm prisma migrate deploy - pnpm prisma:generate + bunx prisma migrate deploy + bun run prisma:generate ``` 4. Popule usuários padrão do Better Auth: ```bash - pnpm auth:seed + bun run auth:seed ``` 5. (Opcional) Para re-sincronizar manualmente as filas padrão, execute: ```bash - pnpm queues:ensure + bun run queues:ensure ``` 6. Em um terminal, execute o backend em tempo real do Convex: ```bash @@ -40,7 +40,7 @@ Aplicação **Next.js 16 (App Router)** com **React 19**, **Convex** e **Better ```bash bun run dev:bun ``` - > Fallback: `pnpm dev` (Node) ou `bun run dev:webpack` caso o Turbopack acione alguma incompatibilidade. + > Fallback: `bun run dev:webpack` caso o Turbopack acione alguma incompatibilidade. 8. Com o Convex ativo, acesse `http://localhost:3000/dev/seed` uma vez para popular dados de demonstração (tickets, usuários, comentários) diretamente no banco do Convex. > Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente. @@ -64,9 +64,9 @@ Para fluxos detalhados de desenvolvimento — banco de dados local (SQLite/Prism ## Scripts úteis -- `bun run dev:bun` — padrão atual para o Next.js com runtime Bun (`pnpm dev` usa Node como fallback). -- `bun run convex:dev:bun` — runtime Bun para o Convex (`pnpm convex:dev` mantém o fluxo antigo). -- `bun run build:bun` / `bun run start:bun` — build e serve com Bun; use `pnpm build`/`pnpm start` se quiser ficar no Node. +- `bun run dev:bun` — padrão atual para o Next.js com runtime Bun (`bun run dev:webpack` permanece como fallback). +- `bun run convex:dev:bun` — runtime Bun para o Convex (`bun run convex:dev` mantém o fluxo antigo usando Node). +- `bun run build:bun` / `bun run start:bun` — build e serve com Bun; `bun run build` mantém o fallback Node. - `bun run dev:webpack` / `bun run build:webpack` — fallback oficial caso Turbopack apresente problemas. - `bun run lint` — ESLint com as regras do projeto. - `bun test` — suíte de testes unitários usando o runner do Bun (o teste de screenshot fica automaticamente ignorado se o matcher não existir). @@ -97,7 +97,7 @@ Sem o reset de agente, o Convex reaproveita o token anterior e o inventário con ## Credenciais de demonstração -Após executar `pnpm auth:seed`, as credenciais padrão ficam disponíveis conforme descrito em `agents.md` (seção “Credenciais padrão”). Ajuste variáveis `SEED_USER_*` se precisar sobrepor usuários ou senhas durante o seed. +Após executar `bun run auth:seed`, as credenciais padrão ficam disponíveis conforme descrito em `agents.md` (seção “Credenciais padrão”). Ajuste variáveis `SEED_USER_*` se precisar sobrepor usuários ou senhas durante o seed. ## Próximos passos diff --git a/agents.md b/agents.md index 9801cf4..633226c 100644 --- a/agents.md +++ b/agents.md @@ -13,23 +13,23 @@ Os demais colaboradores reais são provisionados via **Convites & acessos**. Caso existam vestígios de dados demo, execute `node scripts/remove-legacy-demo-users.mjs` para limpá-los. -> Execute `pnpm auth:seed` após configurar `.env` para (re)criar os usuários acima (campos `SEED_USER_*` podem sobrescrever credenciais). +> Execute `bun run auth:seed` após configurar `.env` para (re)criar os usuários acima (campos `SEED_USER_*` podem sobrescrever credenciais). ## Backend Convex - Seeds de usuários/tickets demo: `convex/seed.ts`. -- Para DEV: rode `pnpm convex:dev` e acesse `/dev/seed` uma vez para popular dados realistas. +- Para DEV: rode `bun run convex:dev:bun` e acesse `/dev/seed` uma vez para popular dados realistas. ## Stack atual (18/10/2025) - **Next.js**: `15.5.5` (Turbopack em produção + cache de filesystem em DEV). - Whitelist de domínios em `src/config/allowed-hosts.ts` é aplicada pelo `middleware.ts`. - **React / React DOM**: `18.2.0`. -- **Trilha de testes**: Vitest (`pnpm test`) sem modo watch por padrão (`--run --passWithNoTests`). -- **CI**: workflow `Quality Checks` (`.github/workflows/quality-checks.yml`) roda `pnpm install`, `prisma:generate`, `lint`, `test`, `build`. Variáveis críticas (`BETTER_AUTH_SECRET`, `NEXT_PUBLIC_APP_URL`, etc.) são definidas apenas no runner — não afetam a VPS. -- **Disciplina pós-mudanças**: sempre que fizer alterações locais, rode **obrigatoriamente** `pnpm lint`, `pnpm build` e `pnpm test` antes de entregar ou abrir PR. Esses comandos são mandatórios também para os agentes/automations, garantindo que o projeto continua íntegro. -- **Deploy**: pipeline `ci-cd-web-desktop.yml` (runner self-hosted). Build roda com pnpm 9, Node 20. Web é publicado em `/home/renan/apps/sistema` e o Swarm aponta `sistema_web` para essa pasta. +- **Trilha de testes**: Vitest (`bun test`) sem modo watch por padrão (`--run --passWithNoTests`). +- **CI**: workflow `Quality Checks` (`.github/workflows/quality-checks.yml`) roda `bun install`, `bun run prisma:generate`, `bun run lint`, `bun test`, `bun run build:bun`. Variáveis críticas (`BETTER_AUTH_SECRET`, `NEXT_PUBLIC_APP_URL`, etc.) são definidas apenas no runner — não afetam a VPS. +- **Disciplina pós-mudanças**: sempre que fizer alterações locais, rode **obrigatoriamente** `bun run lint`, `bun run build:bun` e `bun test` antes de entregar ou abrir PR. Esses comandos são mandatórios também para os agentes/automations, garantindo que o projeto continua íntegro. +- **Deploy**: pipeline `ci-cd-web-desktop.yml` (runner self-hosted). Build roda com Bun 1.3 + Node 20. Web é publicado em `/home/renan/apps/sistema` e o Swarm aponta `sistema_web` para essa pasta. ## Setup local (atualizado) -1. `pnpm install` +1. `bun install` 2. Copie `.env.example` → `.env.local`. - Principais variáveis para DEV: ``` @@ -40,10 +40,10 @@ Os demais colaboradores reais são provisionados via **Convites & acessos**. Cas NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210 DATABASE_URL=file:./prisma/db.dev.sqlite ``` -3. `pnpm auth:seed` -4. (Opcional) `pnpm queues:ensure` -5. `pnpm convex:dev` -6. Em outro terminal: `pnpm dev` +3. `bun run auth:seed` +4. (Opcional) `bun run queues:ensure` +5. `bun run convex:dev:bun` +6. Em outro terminal: `bun run dev:bun` 7. Acesse `http://localhost:3000` e valide login com os usuários padrão. ### Banco de dados @@ -53,9 +53,9 @@ Os demais colaboradores reais são provisionados via **Convites & acessos**. Cas ### Verificações antes de PR/deploy ```bash -pnpm lint -pnpm test -pnpm build +bun run lint +bun test +bun run build:bun ``` ## Aplicativo Desktop (Tauri) @@ -86,11 +86,11 @@ pnpm build - Planejamos usar um cookie `desktop_shell` no futuro para diferenciar acessos do desktop vs navegador (não implementado). ## Qualidade e testes -- **Lint**: `pnpm lint` (ESLint flat config). +- **Lint**: `bun run lint` (ESLint flat config). - **Testes unitários/integrados (Vitest)**: - Cobertura atual inclui utilitários (`tests/*.test.ts`), rotas `/api/machines/*` e `sendSmtpMail`. - - Executar `pnpm test -- --watch` apenas quando precisar de modo interativo. -- **Build**: `pnpm build` (`next build --turbopack`). + - Executar `bun test -- --watch` apenas quando precisar de modo interativo. +- **Build**: `bun run build:bun` (`next build --turbopack`). - **CI**: falhas mais comuns - `ERR_PNPM_OUTDATED_LOCKFILE`: mantenha `pnpm-lock.yaml` atualizado (principalmente após alterar dependências do desktop). - Variáveis Better Auth ausentes (`BETTER_AUTH_SECRET`): definidas no workflow (`Quality Checks`). diff --git a/docs/OPERACAO-PRODUCAO.md b/docs/OPERACAO-PRODUCAO.md index 5b5fdb6..4111a3d 100644 --- a/docs/OPERACAO-PRODUCAO.md +++ b/docs/OPERACAO-PRODUCAO.md @@ -11,7 +11,7 @@ Nota: este documento foi substituído por `docs/operations.md` e permanece aqui - Banco Prisma (SQLite) persistente via volume `sistema_db` (mapeado em `/app/data`). - Estado do Convex persistente via volume `convex_data`. - Seeds prontos (Better Auth e dados demo Convex). - - Seeds Better Auth automáticos: o container do web executa `pnpm auth:seed` após `prisma migrate deploy`, garantindo usuários padrão em toda inicialização (sem resetar senha existente por padrão). +- Seeds Better Auth automáticos: o container do web executa `bun run auth:seed` após `prisma migrate deploy`, garantindo usuários padrão em toda inicialização (sem resetar senha existente por padrão). ### Sessão de dispositivo (Desktop/Tauri) - A rota `GET /machines/handshake?token=...&redirect=/portal|/dashboard` é pública no middleware para permitir a criação da sessão "machine" a partir do agente desktop, mesmo sem login prévio. @@ -249,7 +249,7 @@ O pipeline executa um teste rápido após o deploy do Web: - Usuários (Better Auth): ``` CONTAINER=$(docker ps --format '{{.ID}} {{.Names}}' | grep sistema_web | awk '{print $1}' | head -n1) -docker exec -it "$CONTAINER" bash -lc 'cd /app && pnpm auth:seed' +docker exec -it "$CONTAINER" bash -lc 'cd /app && bun run auth:seed' ``` - Apenas um admin (em produção): ``` @@ -259,9 +259,9 @@ docker exec -it "$CONTAINER" bash -lc 'cd /app && \ SEED_USER_PASSWORD="suaSenhaForte" \ SEED_USER_NAME="Seu Nome" \ SEED_USER_ROLE="admin" \ - pnpm auth:seed' + bun run auth:seed' ``` -- Filas padrão: `docker exec -it "$CONTAINER" bash -lc 'cd /app && pnpm queues:ensure'` +- Filas padrão: `docker exec -it "$CONTAINER" bash -lc 'cd /app && bun run queues:ensure'` ## Atualizações (sem CI) - App (Next.js): @@ -337,4 +337,4 @@ Benefícios - Scripts (package.json): - `dev`: `next dev --turbopack` - `build`: `next build --turbopack` -- O workflow de CI executa `pnpm build` (que já chama Turbopack via script), e a stack utiliza `pnpm start` sobre o artefato gerado. +- O workflow de CI executa `bun run build:bun` (que já chama Turbopack via script), e a stack utiliza `bun run start:bun` sobre o artefato gerado. diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 300a7b5..6900346 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -141,9 +141,9 @@ Depois disso, o job “Deploy Convex functions” funciona em modo não interati ## 7) Testes, Build e Lint - Local - - `pnpm build` (Next + typecheck) - - `pnpm lint` - - `pnpm test` + - `bun run build:bun` (Next + typecheck) + - `bun run lint` + - `bun test` - CI garante build, lint e testes antes do deploy. diff --git a/scripts/deploy-from-git.sh b/scripts/deploy-from-git.sh index c884b13..a2688d7 100644 --- a/scripts/deploy-from-git.sh +++ b/scripts/deploy-from-git.sh @@ -42,7 +42,7 @@ if echo "$CHANGED" | grep -q '^convex/'; then -v "$APP_DIR":/app \ -w /app \ --env-file .ci.env \ - node:20-bullseye bash -lc "corepack enable && corepack prepare pnpm@10.20.0 --activate && pnpm install --frozen-lockfile --prod=false && pnpm exec convex deploy" + node:20-bullseye bash -lc "corepack enable && corepack prepare pnpm@10.20.0 --activate && pnpm install --no-frozen-lockfile --prod=false && pnpm exec convex deploy" else echo "[deploy] convex/ changed but .ci.env missing; skip Convex deploy" fi @@ -51,4 +51,3 @@ else fi echo "[deploy] Done." -