oro dev

Visão geral

Gerencia os dev servers dos seus projetos a partir de um projects.config.json único. Substitui scripts caseiros de gestão de processos sem depender de node, python3, ss ou lsof — só o binário oro e o git para abrir repositórios.

Comandos

oro dev list             # tabela de projetos: ▶ rodando   ! porta ocupada   ○ parado
oro dev list clientes    # só os projetos do grupo (ignora caixa e acentos)
oro dev start api web    # inicia projetos em paralelo (aliases: run, up)
oro dev api              # atalho: `oro dev <atalho>` equivale a `oro dev start <atalho>`
oro dev status           # PID + URL + log de cada projeto rodando
oro dev logs api         # tail do log em tempo real (Ctrl+C para sair)
oro dev open api         # abre o navegador na porta do projeto (xdg-open)
oro dev stop api         # para o projeto: SIGTERM → 3s → SIGKILL no grupo (sem --force)
oro dev stop --all       # para todos os projetos
oro dev add              # wizard interativo com sugestão da próxima porta livre

start e stop terminam exibindo a mesma tabela do list, restrita aos projetos que estão rodando ("Projetos rodando em: ..."); se não restar nenhum, a tabela é omitida.

O arquivo projects.config.json

Resolução do caminho: --config sobrepõe; sem ele, $CLIENTES_HOME/projects.config.json. Dá para criar as entradas pelo wizard oro dev add ou editar o JSON à mão — a ordem de inserção dos projetos é preservada e o save é determinístico (2 espaços, diff limpo, round-trip byte-idêntico para config sem grupo).

{
  "projects": {
    "projeto-a": {
      "name": "Projeto A (Sistema)",
      "path": "/home/voce/dev/clientes/projeto-a",
      "cwd": "/home/voce/dev/clientes/projeto-a/apps/web",
      "package_manager": "pnpm",
      "dev_command": "pnpm dev",
      "port": 3001,
      "description": "Monorepo Next.js - Sistema Projeto A",
      "group": "Clientes"
    }
  },
  "settings": {
    "log_dir": ".dev-logs",
    "pid_dir": ".dev-pids",
    "enforce_unique_ports": true
  }
}

projects

Cada chave é o atalho usado nos comandos (oro dev <atalho> equivale a oro dev start <atalho>).

Campo	Tipo	Descrição
name	string	Nome exibido na tabela do list.
path	string	Raiz do projeto.
cwd	string	Diretório onde o comando roda (monorepos); vazio = path.
package_manager	string	npm ou pnpm.
dev_command	string	Comando do dev server; menções a vite/next definem a faixa de porta sugerida pelo add (next 3001–3099, vite 5174–5199).
port	número | null	Porta do serviço; null/ausente = sem porta (ex.: workers). Base da checagem de prontidão pós-start e do open.
description	string	Descrição curta.
group	string (opcional)	Grupo do projeto — ver Grupos.

settings

Campo	Default	Descrição
log_dir	.dev-logs	Diretório dos logs; caminho relativo ao diretório do config (ou absoluto).
pid_dir	.dev-pids	Diretório dos pids; mesmo critério.
enforce_unique_ports	false	Com true, o start fixa a porta configurada: flags do vite/next/wrangler, -- --port para wrappers npm e env PORT/HOST/NODE_ENV. Sem ele, o comando roda como está.

Grupos

Projetos podem ter um grupo opcional — campo "group" por projeto no projects.config.json. O conjunto de grupos é derivado dos projetos; não existe cadastro de grupos.

oro dev list clientes       # só os projetos do grupo Clientes
oro dev list clientes saas  # união de dois grupos

• Matching ignora caixa e acentos: clientes casa Clientes, configuracoes casa Configurações; a exibição usa sempre o valor gravado no config.
• Grupo inexistente é erro, listando os grupos disponíveis.
• Coluna "Grupo" aparece só quando as linhas exibidas têm 2+ valores distintos: sem nenhum grupo (config legado) ou com todas as linhas no mesmo grupo, a coluna é omitida por redundância — projetos sem grupo mostram —.
• oro dev add pede o grupo (opcional) no wizard; grupo novo nasce no primeiro uso.

Flags globais

Flag	Default	Descrição
--config	—	Caminho do projects.config.json (sobrepõe a resolução padrão)
--clients-home	$CLIENTES_HOME	Diretório base dos projetos
--wait	30s	Tempo máximo aguardando o serviço ficar pronto após o start
--no-wait	false	Não aguardar prontidão pós-start (comportamento legado)

Comportamento importante

• Kill de árvore — stop envia o sinal ao grupo do processo (Setpgid), eliminando processos filhos órfãos; não existe --force.
• Portas — verificação de porta ocupada via net.Listen; add valida unicidade de porta no config e sugere a próxima livre da faixa do comando dev.
• Logs/pids — arquivos em .dev-logs/ e .dev-pids/ ao lado do config.
• Prontidão pós-start — start não termina no spawn: com porta configurada, ele aguarda o serviço aceitar conexões em localhost (✓ "no ar"); boot mais lento que --wait sai como aviso "! ainda subindo" (não é falha — acompanhe com oro dev logs); processo que morre no boot sai como erro ✗ com as últimas linhas do log. Projetos sem porta só têm a verificação de o processo sobreviver à subida.