@micelize/cli

CLI da Micelize: conversa com a API do gestor pela linha de comando, sob a permissão de quem está logado. O token (JWT) carrega o conjunto fractal de permissões; o guard do backend aplica o Perm de cada rota — a CLI só manda a requisição e mostra o resultado (ou o 403).

A ferramenta é fractal como o backend: cada MÓDULO do gestor vira um grupo de subcomandos. Grupos de hoje: modula (o registro de módulos, que também faz trabalho local de filesystem), deploys (previews de projeto), ramos (a unidade fractal de trabalho), tickets (os chamados dos sistemas de cliente, por ramo), whatsapp (as linhas que você lê: abrir conversa do atendimento, enviar com --confirmar, ler; e o canal simulado p/ testar agentes), chat, principios e settings. Os próximos (atendimentos, clientes…) entram sob demanda, um require por grupo em src/cli.js.

Uso

micelize login                     # autentica no gestor e guarda o token
micelize modula search auth        # busca módulos no registro
micelize modula publish ./meu-mod  # publica uma versão (metadados no modula.yaml)
micelize modula install            # resolve o fecho e monta no projeto
micelize modula docs               # explica o formato do modula.yaml

MICELIZE_API_URL sobrescreve a API (padrão: https://api.gestor.micelize.com). O token é herdado do ~/.modula antigo na primeira execução (transição sem re-login) e passa a viver em ~/.micelize/config.json.

O acesso: quanto dura e como se renova

O gestor emite um acesso com prazo (hoje, 8 horas). O CLI cuida dele sozinho:

• a cada comando, se o acesso ainda vale e já passou da metade do prazo, o CLI pede um novo ao gestor e o guarda. Quem usa o CLI ao menos uma vez dentro do prazo não cai mais no meio do trabalho;
• acesso vencido não vira "token inválido": o CLI diz há quanto tempo venceu, quanto durava e o comando que resolve, sem nem chamar a API;
• micelize sessao mostra quanto falta (sai com 1 se não há acesso ou se ele venceu, para script e agente perguntarem antes de começar); --renovar troca agora; micelize whoami mostra o mesmo junto das permissões.

O que isto não cobre é o intervalo maior que o prazo (a noite sem uso): renovar exige um acesso ainda válido. MICELIZE_NO_RENEW=1 desliga a renovação automática. O arquivo do acesso é gravado só para o dono (modo 600).

Para script e para agente

• --json vale no programa inteiro, antes ou depois do subcomando (micelize --json ramos list ou micelize ramos list --json), e devolve o que a API respondeu. Hoje respeitam: whoami, sessao, ramos (list, tree, show, stages, move, comments, comment, create, update, attach, attachments, download) e deploys (create, list, backend, env list, request, requests list/show/logs/wait/approve). O resto (ramos brief, indicators, link e concepts, deploys rollback, env set/unset e reject, e os outros grupos) segue com a saída de gente.
• Código de saída. Comando que falha sai com 1 (antes saía 0, e quem encadeava com && seguia em frente). deploys requests approve e wait contam o desfecho: 0 = montagem concluída, 1 = falhou ou foi rejeitada, 2 = não terminou no prazo.

Ramos: o que mudou no uso

micelize ramos show 652 --resumo            # nome, estado, coluna e contagens, sem o diário inteiro
micelize ramos comments 652 --ultimos 3     # só as últimas considerações
micelize ramos stages --parent 47           # as colunas do quadro do pai
micelize ramos move 658 --stage 518         # confere que a coluna é do quadro do ramo
micelize ramos create "Projeto" --parent 47 --stage 187 --attendance 138 --client 116
micelize ramos attach 656 --file recibo.pdf # sobe um arquivo (ou --url, para um link)
micelize ramos attachments 656              # lista os anexos
micelize ramos download 656 10 -o ./baixados  # baixa um; o nome ganha a extensão do tipo

ramos move (e create --stage) recusa coluna de outro quadro: a API aceita qualquer id e o ramo sumia do quadro em silêncio. A recusa lista as colunas válidas; --forcar pula a conferência.

Deploys: acompanhar uma montagem

micelize deploys requests approve grafite 461 --env dev   # aprova e roda; a saída conta o desfecho
micelize deploys requests wait grafite 461 --env dev      # espera terminar (--timeout min, --intervalo s)
micelize deploys requests logs grafite 461 --env dev --ultimas 40   # só o log, sem o script

Aprovação se dá uma vez. O approve roda a montagem na própria requisição: se o terminal cair ou vier um 504, ela segue no gestor. Repetir o approve atropela a que está rodando e as duas falham: use requests wait. Enquanto a montagem roda, o estado continua pending (o gestor só o grava no fim), então daqui não dá para distinguir "esperando aprovação" de "rodando".

deploys env list também grava: na primeira vez ele semeia a env padrão do projeto. É de propósito (a primeira montagem roda sem env se ninguém listar antes), mas não é uma leitura inocente.

Estrutura (uma responsabilidade por lugar)

bin/micelize.js          entry (só despacha o argv)
src/cli.js               monta o programa e registra os grupos
src/commands/auth.js     login / logout / whoami / sessao (topo — token compartilhado)
src/commands/modula/     o grupo modula, um verbo por arquivo
src/lib/                 config · pack · tokens · assemble · manifest
                         session (o prazo do acesso) · program (--json e a renovação,
                         antes de cada comando) · output · stages · requests
test/                    as contas puras e o CLI inteiro contra um gestor de mentira

Provar e publicar

npm test                 # as provas (rodam sozinhas antes de todo `npm publish`)
npm pack --dry-run       # o que entraria no pacote: bin, src, examples e o README

Versão nova é version no package.json (SemVer) no mesmo commit da mudança.

O modula standalone (@micelize/modula) segue existindo; este pacote o absorve como subcomando e é o caminho a partir daqui.