Comandos, arquivos e configuração

Um comando vai no terminal

Um terminal é a janela onde você digita instruções para o seu computador. Em Visual Studio Code, primeiro abra sua pasta supastack usando Arquivo → Abrir pasta e selecione Terminal → Novo Terminal. O novo terminal começa nessa pasta. No Windows escolha PowerShell usando o menu próximo ao botão + do terminal. Use blocos macOS/Linux em um terminal macOS ou Linux.

Cole apenas o conteúdo de um bloco de comando, um comando por vez, e pressione Enter. Não cole os crases do Markdown ao redor, um prompt como PS C:\... ou uma saída de exemplo. As linhas que começam com # são explicações; eles não executam nada. Aguarde a conclusão de cada comando de instalação antes de inserir o próximo comando. Um comando do servidor continua em execução e não retorna um novo prompt até que você o interrompa.

Verifique qual pasta o terminal está usando

Raiz do repositório significa a pasta supastack de nível superior contendo package.json, pnpm-workspace.yaml, aplicativos e pacotes. A menos que uma etapa indique o contrário, execute comandos lá. O comando abaixo imprime a pasta atual; a listagem de arquivos deve mostrar package.json. No Windows PowerShell pwd e ls também funcionam.

Se a listagem mostrar apenas o conteúdo de apps/desktop, digite cd ../.. e pressione Enter para voltar à raiz. Se mostrar sua pasta pessoal, digite cd seguido de um espaço e o caminho completo para o seu clone, entre aspas quando contiver espaços. Normalmente é mais fácil abrir a pasta do projeto no editor e criar um novo terminal.

pwd
ls

A configuração vai em um arquivo, não no terminal

Um bloco como AI_PROVIDER=fake é um texto de configuração. Abra o arquivo .env nomeado no editor, encontre a linha que começa com AI_PROVIDER=, substitua seu valor e salve com Ctrl + S (Command + S no macOS). Cada configuração ocupa uma linha no formato KEY=value. Não adicione crases Markdown. Evite cópias duplicadas da mesma chave em um arquivo.

Use o .env da raiz para comandos de migração de banco de dados e apps/web/.env.local para o backend Web — em um checkout somente Desktop, esse arquivo pertence ao repositório backend separado. O shell desktop não lê arquivos .env: SUPASTACK_APP_URL é uma configuração de ambiente do terminal que você passa na linha de comando ao iniciá-lo, não uma configuração armazenada num arquivo. Mantenha o arquivo de exemplo inalterado para referência.

Arquivos cujos nomes começam com um ponto podem estar ocultos no seu gerenciador de arquivos; o Explorer do editor os mostra. Certifique-se de que o nome do arquivo seja exatamente .env.local, não .env.local.txt. Esses arquivos locais podem conter senhas e são excluídos do Git; não os carregue nem cole seu conteúdo em mensagens de suporte.

• Encontre o significado de cada configuração

Mantenha o comando dev em execução; use outro terminal para comandos

O comando de desenvolvimento desktop compila o shell Rust e abre a janela enquanto roda. Deixe o terminal dele aberto enquanto você testa a janela. Um comando de servidor continua em execução e não retorna um novo prompt até você pará-lo.

Para executar outro comando enquanto o servidor estiver ativo, selecione Terminal → Novo Terminal no editor. O novo terminal é uma janela separada no mesmo projeto. Para parar o servidor, selecione seu terminal e pressione Ctrl + C uma vez. No Windows, se for solicitado Encerrar trabalho em lote, digite Y e pressione Enter. Aguarde o prompt normal antes de iniciá-lo novamente.

Depois de alterar as configurações do shell, pare o comando desktop com Ctrl + C e execute-o novamente. O núcleo Rust recompila a cada início; alterar SUPASTACK_APP_URL significa passar o novo valor na próxima execução, não editar um arquivo salvo.

corepack pnpm --filter @supastack/desktop dev

Leia uma falha e peça ajuda útil

Se uma instalação retornar um texto de erro em vermelho, pare nessa etapa. Leia o primeiro erro em vez de continuar a iniciar o aplicativo. Comando não encontrado geralmente significa uma ferramenta ausente; nenhum package.json geralmente significa a pasta errada; ECONNREFUSED geralmente significa que um servidor ou banco de dados necessário não está em execução; EADDRINUSE significa que outro processo já usa a porta.

Ao pedir ajuda, inclua seu sistema operacional, o guia URL e o número da etapa, o comando exato que você digitou e a primeira mensagem de erro. Remova senhas, chaves API, tokens e a parte da senha de qualquer banco de dados URL. Não envie seus arquivos .env. Uma captura de tela do erro pode ajudar, mas o texto copiável é mais fácil de diagnosticar.

• Solucionar uma falha de configuração específica