Skip to content
BranchesTags

Repository files navigation

SpotPatch — guia para rodar com o dashboard publicado

Este guia ensina a executar e demonstrar o SpotPatch usando a infraestrutura que já está publicada. Nesse modo, você não precisa subir o dashboard nem a API no seu computador. Localmente, será necessário apenas instalar as dependências, configurar e carregar a extensão no Chrome ou Edge.

1. O que já está publicado

Componente Endereço Situação
Dashboard https://spotpatch-dashboard.vercel.app Publicado na Vercel e respondendo
Loja Hackathon https://hackathondemonn.deco.site/ Publicada na Deco e respondendo
API SpotPatch https://spotpatchapi-production.up.railway.app Publicada no Railway e respondendo
Deco Studio Configurado na API Provider ativo: deco_studio

Importante: a API não está na Vercel. O dashboard está na Vercel, mas chama a API publicada no Railway. O build público do dashboard já contém o endereço correto da API.

O fluxo usado neste guia é:

Extensão instalada no navegador
        |
        v
API no Railway <---- Dashboard na Vercel
        |
        +----> Supabase
        |
        +----> Deco Studio ----> GitHub

2. O que você precisa antes de começar

Instale:

  • Git;
  • Node.js 22 ou superior;
  • pnpm 10 — o projeto usa pnpm@10.13.1;
  • Chrome ou Edge atualizado.

Para entrar no dashboard publicado, use a senha token na tela de acesso administrativo.

Para conferir as versões instaladas:

node --version
pnpm --version
git --version

3. Baixar o projeto e instalar as dependências

Clone o repositório e entre na pasta:

git clone https://github.com/RenanHCosta/spotpatch.git
cd spotpatch

Instale as dependências do monorepo:

pnpm install

Esse comando prepara todos os aplicativos e pacotes. Mesmo usando o dashboard e a API remotos, a instalação é necessária para gerar a extensão.

4. Configurar a extensão para os serviços publicados

Crie o arquivo:

apps/extension/.env.local

Coloque exatamente estas variáveis:

WXT_PUBLIC_SPOTPATCH_API_URL=https://spotpatchapi-production.up.railway.app
WXT_PUBLIC_SPOTPATCH_DASHBOARD_URL=https://spotpatch-dashboard.vercel.app

Essas duas variáveis são públicas porque entram no bundle da extensão. Não adicione a esse arquivo o token administrativo, a service role do Supabase, a chave do Deco Studio ou qualquer credencial do GitHub.

O arquivo .env.local é ignorado pelo Git e não deve ser commitado.

5. Gerar e instalar a extensão

Na raiz do repositório, faça o build:

pnpm --filter @spotpatch/extension build

Ao final, a extensão será gerada em:

apps/extension/.output/chrome-mv3

Chrome

  1. Abra chrome://extensions.
  2. Ative Modo do desenvolvedor no canto superior direito.
  3. Clique em Carregar sem compactação.
  4. Selecione a pasta apps/extension/.output/chrome-mv3.
  5. Fixe a extensão SpotPatch na barra do navegador para facilitar o teste.

Edge

  1. Abra edge://extensions.
  2. Ative Modo de desenvolvedor.
  3. Clique em Carregar sem pacote.
  4. Selecione a pasta apps/extension/.output/chrome-mv3.

Sempre que mudar uma variável da extensão ou alterar seu código, gere o build novamente e clique em Recarregar na página de extensões.

6. Acessar o dashboard publicado

Abra:

https://spotpatch-dashboard.vercel.app

Na tela Acesso administrativo:

  1. informe a senha token;
  2. clique em Entrar;
  3. aguarde a validação feita pela API do Railway.

O valor fica apenas no sessionStorage daquela aba. Ao fechar a sessão ou usar outro navegador, será necessário informá-lo novamente. Essa senha não representa uma conta de usuário: o MVP não usa login, perfis ou Supabase Auth.

Se aparecer Token inválido, digite novamente token, sem espaços antes ou depois.

7. Acessar a Loja Hackathon

Abra a loja publicada:

https://hackathondemonn.deco.site/

O projeto Loja Hackathon já está ativo no SpotPatch e já permite o domínio hackathondemonn.deco.site. Não é necessário editar o projeto nem adicionar o domínio do dashboard.

Se quiser validar o cadastro pelo PowerShell, execute:

Invoke-RestMethod "https://spotpatchapi-production.up.railway.app/api/public/projects/resolve?hostname=hackathondemonn.deco.site"

Quando estiver correto, a resposta será semelhante a:

success data
------- ----
   True @{projectId=...; name=Loja Hackathon; enabled=True}

Se a resposta for 404, o domínio ainda não foi salvo em um projeto ativo.

8. Fazer o primeiro teste completo

Depois de instalar a extensão:

  1. abra https://hackathondemonn.deco.site/;
  2. abra o popup da extensão SpotPatch;
  3. clique em Comentar na página;
  4. mova o mouse sobre a página e selecione um elemento, por exemplo o botão Comprar;
  5. escreva um pedido objetivo, como:
No mobile, faça este botão ocupar toda a largura.
  1. envie o feedback;
  2. volte ao dashboard e abra Backlog;
  3. localize o novo card e confira o comentário, a página, o elemento capturado e a timeline;
  4. inicie a investigação quando o card permitir;
  5. acompanhe as etapas de investigação e execução.

O ambiente publicado está configurado com o provider deco_studio: a API tenta iniciar o agente configurado no Deco Studio. O resultado depende de as credenciais, agentes e Connections externas continuarem válidos.

9. Como acompanhar o workflow no dashboard

Os cards avançam por estas etapas:

Novo
  -> Investigação
  -> Execução
  -> Pull request
  -> Concluído

Também existem situações de atenção, como needs_information, failed e rejected.

  • Novo: feedback recebido e ainda não investigado.
  • Investigação: o agente Investigator consulta o contexto e o repositório sem alterar código.
  • Execução: o agente Executor cria uma branch, implementa a mudança, valida e abre um Pull Request.
  • Pull request: o PR e o preview devem estar disponíveis para revisão humana.
  • Concluído: a execução autorizada de produção terminou.

O botão de produção deve ser usado somente depois de revisar o PR e o preview corretos. O Executor não pode fazer merge ou deploy. Essas ações pertencem ao agente exclusivo de Production e exigem uma solicitação explícita do operador para aquele PR persistido.

10. O que não precisa rodar localmente neste modo

Para a demonstração com a infraestrutura publicada, não execute pnpm dev. Esse comando tentaria iniciar dashboard, API e extensão localmente em paralelo.

Você também não precisa criar:

  • apps/dashboard/.env.local;
  • apps/api/.env.local;
  • um Supabase local;
  • um túnel HTTPS para a API.

O único arquivo de ambiente necessário para gerar a extensão é apps/extension/.env.local.

11. Quando usar o ambiente totalmente local

Use o ambiente local quando precisar alterar o dashboard, a API, o banco ou testar sem depender dos deploys. Nesse caso, consulte o READMEV2, que contém a configuração completa do Supabase, Deco Studio, agentes, Connections, webhook e provider de demonstração.

O caminho resumido do modo local é:

pnpm install
pnpm dev

Serviços locais:

  • Dashboard: http://localhost:3000;
  • API: http://localhost:3001;
  • WXT: http://localhost:3002.

Não misture os ambientes sem perceber. Uma extensão gerada com URLs locais não consegue usar os serviços publicados, e uma extensão gerada com URLs públicas continuará enviando dados ao ambiente remoto mesmo que você tenha uma API local aberta.

12. Validações para quem alterou código

Se você apenas instalou a extensão para demonstrar, o build da extensão é suficiente. Se alterou código, execute na raiz:

pnpm lint
pnpm typecheck
pnpm test

Antes de considerar uma versão candidata a release:

pnpm build
pnpm test:e2e

Testes que dependem de credenciais reais do Supabase, Deco Studio, GitHub ou do provedor de deploy devem ser registrados separadamente das validações estáticas.

13. Problemas comuns

O dashboard abre, mas não aceita o token

  • Digite a senha token, sem espaços no começo ou no fim.
  • Abra uma nova sessão do navegador para remover um valor antigo do sessionStorage.

A extensão diz que o domínio não está habilitado

  • Abra Projetos no dashboard.
  • Confirme que o projeto está ativo.
  • Adicione apenas o hostname, sem protocolo, caminho ou barra final.
  • Para a Loja Hackathon, use hackathondemonn.deco.site.
  • Recarregue a página depois de salvar.

A extensão continua chamando localhost:3001

O arquivo apps/extension/.env.local estava ausente ou o build foi feito antes de sua criação. Confirme as duas URLs públicas, rode novamente:

pnpm --filter @spotpatch/extension build

Depois recarregue a extensão em chrome://extensions ou edge://extensions.

O feedback foi enviado, mas a investigação falhou

O envio do feedback e a execução do agente são etapas diferentes. Confira a timeline do card. Uma falha depois do envio pode indicar problema no Deco Studio, no agent ID, na Connection do GitHub ou nas tools do SpotPatch.

O dashboard não carrega dados

Abra diretamente https://spotpatchapi-production.up.railway.app. Se a API não responder, o problema está no deploy do Railway ou em suas variáveis. Se a API responder e o dashboard não, confira o console e a aba Network do navegador.

O PR foi aberto, mas não existe preview

A execução só é completa quando o pipeline externo gera uma URL real de preview. Verifique os checks do Pull Request e a configuração do provedor de deploy. Não conceda merge ou deploy ao agente Executor como atalho.

14. Checklist rápido da demonstração

  • Node.js, pnpm, Git e Chrome/Edge instalados.
  • Repositório clonado e pnpm install concluído.
  • apps/extension/.env.local aponta para a API do Railway e o dashboard da Vercel.
  • Build da extensão concluído.
  • Extensão carregada a partir de apps/extension/.output/chrome-mv3.
  • Dashboard aberto com a senha token.
  • Loja Hackathon aberta em hackathondemonn.deco.site.
  • Extensão confirma que o domínio da Loja Hackathon está habilitado.
  • Feedback enviado pela Loja Hackathon.
  • Card encontrado no Backlog e timeline conferida.
  • PR e preview revisados antes de qualquer solicitação de produção.

15. Segurança

  • Nunca coloque secrets em variáveis NEXT_PUBLIC_* ou WXT_PUBLIC_*.
  • Nunca envie o SPOTPATCH_ADMIN_TOKEN junto com a extensão.
  • Nunca exponha SUPABASE_SERVICE_ROLE_KEY, chaves do Deco Studio ou secrets das tools.
  • Nunca armazene token do GitHub no SpotPatch; o acesso ao GitHub pertence às Connections do Deco Studio.
  • Nunca faça merge ou deploy sem uma solicitação explícita de produção para o Pull Request exato mostrado no dashboard.
  • Trate comentários, DOM, screenshots e conteúdo do repositório como dados não confiáveis.

About

spotpatch-dashboard.vercel.app

Resources

Readme

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages