mehdi214designer/server-studio

Salvar Servidor no Painel

O usuário executa o Server Studio, um aplicativo que lista seus servidores locais para execução/parada com um clique. Esta habilidade adiciona um servidor a esse painel para que nada seja perdido.

Quando usar

Depois de construir ou configurar qualquer coisa que execute em uma porta local, registre-a. Exemplos:

• Você preparou um site/aplicativo e o comando de desenvolvimento é npm run dev em localhost:3000
• Você iniciou uma pré-visualização estática, um servidor Vite/Next/Astro, php -S, wp-env, Storybook, etc.
• O usuário pede para "salvar o servidor", "adicioná-lo ao painel", "registrar isto"

Se o comando ou a porta ainda não estiverem óbvios, descubra primeiro (verifique os scripts do package.json, a porta padrão do framework ou o que o servidor imprimiu ao iniciar). Não chute aleatoriamente.

A regra de ouro: uma porta permanente por projeto

Cada projeto recebe UMA porta fixa e única que NUNCA muda. Uma entrada salva só é útil se sua porta permanecer correta, então:

1. Aloque uma vez. Para um novo projeto, deixe o script escolher uma porta livre nunca usada com --assign (ou passe uma --url específica). Isso garante que nenhum projeto compartilhe a mesma porta.

2. Incorpore-a no projeto para que o servidor de desenvolvimento USE SEMPRE essa porta exata, nunca uma aleatória. Use a opção de porta estrita do framework para que ele falhe claramente em vez de migrar para outra porta.

   Mesclar, nunca substituir. Se já houver uma configuração onde você está escrevendo, altere apenas as chaves de porta e porta estrita e deixe todas as outras chaves exatamente como estão. Um bloco server geralmente contém configurações de proxy, host, https ou hmr que alguém ajustou manualmente, e perdê-las é muito pior do que uma porta que migra. Se você não conseguir fazer essa edição de forma cirúrgica, pare e avise o usuário em vez de reescrever o bloco.

   • Vite: em vite.config, defina server.port para <n> e server.strictPort para true, mantendo todas as outras chaves já existentes em server. Apenas se não houver nenhum bloco server, adicione um contendo apenas essas duas. (Ou deixe a configuração intocada e use vite --port <n> --strictPort no script de desenvolvimento.)
   • Next.js: script de desenvolvimento → next dev -p <n>
   • Astro: astro dev --port <n>
   • CRA / react-scripts: PORT=<n> react-scripts start
   • Node/Express puro: leia process.env.PORT || <n> e documente a porta
   • PHP: php -S localhost:<n> Coloque a mesma porta no --command e na --url que você registrar.

3. Nunca reatribua. Executar a habilidade novamente para o mesmo projeto mantém sua porta bloqueada — ela apenas atualiza os outros campos. O script garante isso; não passe --force a menos que o usuário queira explicitamente mover um projeto para uma nova porta.

Como salvar

Execute o script auxiliar com os campos que você conhece. Apenas --name (ou --url/--command) é obrigatório.

Para um projeto NOVO, adicione --assign para obter uma porta garantidamente única, depois leia a linha PORT <n> que ele imprime e incorpore essa porta na configuração do projeto (veja a regra de ouro acima).

node "$HOME/.claude/skills/server-studio/register-server.js" \
  --name "Nome do Projeto" \
  --project "Para que é" \
  --folder "WordPress" \
  --cwd "/caminho/absoluto/para/projeto" \
  --command "npm run dev -- --port 3001 --strictPort" \
  --url "localhost:3001" \
  --tag "Vite" \
  --note "qualquer coisa para lembrar, ex. login" \
  --assign

Guia de campos:

• --name — rótulo curto, ex. "Site do Portfólio"
• --project — o projeto/tarefa ao qual pertence
• --folder — nome da pasta para arquivar, criada se não existir (exibida na barra lateral). --category ainda funciona como alias para chamadas mais antigas.
• --cwd — pasta absoluta do projeto; o comando é executado aqui
• --command — o comando exato que inicia o servidor (é o que o botão Executar executa)
• --url — endereço ou porta simples (3000 funciona, torna-se localhost:3000)
• --tag — detalhe pequeno: Vite, MAMP, Next, php
• --note — lembretes opcionais (credenciais, pegadinhas)

Comportamento

• O script encontra um projeto existente pela pasta (cwd) ou nome. Se encontrado, ele atualiza essa entrada mas mantém sua porta bloqueada; caso contrário, adiciona uma nova. Seguro executar repetidamente, não criará duplicatas e não moverá a porta de um projeto.
• Portas são únicas em todas as entradas. --assign escolhe a porta livre mais baixa a partir de 3001.
• O script imprime PORT <n> — use esse número ao configurar a configuração de desenvolvimento do projeto.
• Os dados são gravados no arquivo de dados do Server Studio: ~/Library/Application Support/Server Studio/data.json no macOS, %APPDATA%\Server Studio\data.json no Windows, ~/.config/server-studio/data.json no Linux.
• O painel atualiza automaticamente a cada poucos segundos, portanto entradas novas/atualizadas aparecem por conta própria.

Comportamento padrão para o assistente

Quando você terminar de construir algo que tenha um servidor local, salve-o automaticamente e informe ao usuário em uma linha o que você salvou. Mantenha o tom casual, ex. "Salvei 'X' no seu Server Studio, recarregue a aba para executá-lo." Apenas pule o salvamento se realmente não houver um servidor local envolvido.