Files
msd-core/docs/pt-BR/CLI-TOOLS.md
Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
2026-10-06 01:47:40 +02:00

504 lines
19 KiB
Markdown

# Referência de Ferramentas CLI do MSD
> Referência para o CLI `msd-tools` (`msd-core/bin/msd-tools.cjs`). Para comandos slash e fluxos de usuário, consulte a [Referência de Comandos](COMMANDS.md). Voltar ao [índice de documentação](README.md).
---
## Visão Geral
`msd-tools.cjs` centraliza a análise de configuração, resolução de modelos, busca de fases, commits git, verificação de resumos, gerenciamento de estado e operações de templates em comandos, fluxos de trabalho e agentes do MSD.
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Caminho instalado** | `msd-core/bin/msd-tools.cjs` |
| **Implementação** | 20 módulos de domínio em `msd-core/bin/lib/` (o diretório é autoritativo) |
| **Status** | Principal superfície de comandos em tempo de execução para orquestração, fluxos de trabalho e automação. |
**Uso (CJS):**
```bash
node msd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**Flags globais (CJS):**
| Flag | Descrição |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw` | Saída legível por máquina (JSON ou texto simples, sem formatação) |
| `--cwd <path>` | Substitui o diretório de trabalho (para subagentes em sandbox) |
| `--ws <name>` | Contexto de fluxo de trabalho para caminhos `.planning/workstreams/<name>` |
---
## Comandos de Estado
Gerencia `.planning/STATE.md` — a memória viva do projeto.
```bash
# Carrega configuração completa do projeto + estado como JSON
node msd-tools.cjs state load
# Exibe o frontmatter do STATE.md como JSON
node msd-tools.cjs state json
# Atualiza um único campo
node msd-tools.cjs state update <field> <value>
# Obtém o conteúdo do STATE.md ou uma seção específica
node msd-tools.cjs state get [section]
# Atualiza múltiplos campos em lote
node msd-tools.cjs state patch --field1 val1 --field2 val2
# Incrementa o contador de planos
node msd-tools.cjs state advance-plan
# Registra métricas de execução
node msd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
# Recalcula a barra de progresso
node msd-tools.cjs state update-progress
# Adiciona uma decisão
node msd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# Ou a partir de arquivos:
node msd-tools.cjs state add-decision --summary-file path [--rationale-file path]
# Adiciona/resolve bloqueadores
node msd-tools.cjs state add-blocker --text "..."
node msd-tools.cjs state resolve-blocker --text "..."
# Registra continuidade da sessão
node msd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# Início de fase — atualiza Status/Última atividade do STATE.md para uma nova fase
node msd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# Sinalização de bloqueador detectável por agentes (usado por discuss-phase / fluxos de UI)
node msd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node msd-tools.cjs state signal-resume
```
### Snapshot de Estado
Análise estruturada do STATE.md completo:
```bash
node msd-tools.cjs state-snapshot
```
Retorna JSON com: posição atual, fase, plano, status, decisões, bloqueadores, métricas, última atividade.
---
## Comandos de Fase
Gerencia fases — diretórios, numeração e sincronização com o roadmap.
```bash
# Localiza diretório de fase pelo número
node msd-tools.cjs find-phase <phase>
# Calcula o próximo número de fase decimal para inserções
node msd-tools.cjs phase next-decimal <phase>
# Adiciona nova fase ao roadmap + cria diretório
node msd-tools.cjs phase add <description>
# Insere fase decimal após a existente
node msd-tools.cjs phase insert <after> <description>
# Remove fase, renumera as subsequentes
node msd-tools.cjs phase remove <phase> [--force]
# Marca a fase como concluída, atualiza estado + roadmap
node msd-tools.cjs phase complete <phase>
# Indexa planos com ondas e status
node msd-tools.cjs phase-plan-index <phase>
# Lista fases com filtragem
node msd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```
---
## Comandos de Roadmap
Analisa e atualiza o `ROADMAP.md`.
```bash
# Extrai a seção de fase do ROADMAP.md
node msd-tools.cjs roadmap get-phase <phase>
# Análise completa do roadmap com status em disco
node msd-tools.cjs roadmap analyze
# Atualiza linha da tabela de progresso a partir do disco
node msd-tools.cjs roadmap update-plan-progress <N>
```
---
## Comandos de Configuração
Lê e grava em `.planning/config.json`.
```bash
# Inicializa config.json com valores padrão
node msd-tools.cjs config-ensure-section
# Define um valor de configuração (notação de ponto)
node msd-tools.cjs config-set <key> <value>
# Obtém um valor de configuração
node msd-tools.cjs config-get <key>
# Define o perfil de modelo
node msd-tools.cjs config-set-model-profile <profile>
```
---
## Resolução de Modelos
```bash
# Obtém o modelo para um agente com base no perfil atual
node msd-tools.cjs resolve-model <agent-name>
# A saída bruta retorna o ID/tier do modelo selecionado.
# A saída JSON também inclui o perfil e, quando o runtime ativo suporta,
# reasoning_effort.
```
Nomes de agentes: `msd-planner`, `msd-executor`, `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-roadmapper`, `msd-debugger`, `msd-codebase-mapper`, `msd-nyquist-auditor`
---
## Comandos de Verificação
Valida planos, fases, referências e commits.
```bash
# Verifica arquivo SUMMARY.md
node msd-tools.cjs verify-summary <path> [--check-count N]
# Verifica estrutura + tarefas do PLAN.md
node msd-tools.cjs verify plan-structure <file>
# Verifica se todos os planos têm resumos
node msd-tools.cjs verify phase-completeness <phase>
# Verifica se @-refs + caminhos resolvem
node msd-tools.cjs verify references <file>
# Verifica hashes de commit em lote
node msd-tools.cjs verify commits <hash1> [hash2] ...
# Verifica must_haves.artifacts
node msd-tools.cjs verify artifacts <plan-file>
# Verifica must_haves.key_links
node msd-tools.cjs verify key-links <plan-file>
```
---
## Comandos de Validação
Verifica a integridade do projeto.
```bash
# Verifica numeração de fases, sincronização disco/roadmap
node msd-tools.cjs validate consistency
# Verifica integridade de .planning/, com opção de reparo
node msd-tools.cjs validate health [--repair]
# Verifica utilização da janela de contexto para linha de status / chamadores de hook (v1.40.0)
node msd-tools.cjs validate context
# Utilização de contexto como superfície JSON tipada (#455)
node msd-tools.cjs validate context --json
```
`validate context` emite um envelope estruturado com `utilization`, `status`
(`ok` / `warn` / `critical` nos limites de 60% / 70%), e uma
string `suggestion`. Os mesmos dados sustentam `/msd-health --context`.
Passe `--json` para receber o IR tipado diretamente (útil em scripts e asserções de teste).
---
## Comandos de Template
Seleção e preenchimento de templates.
```bash
# Seleciona o template de resumo com base na granularidade
node msd-tools.cjs template select <type>
# Preenche o template com variáveis
node msd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
```
Tipos de template para `fill`: `summary`, `plan`, `verification`
---
## Comandos de Frontmatter
Operações CRUD de frontmatter YAML em qualquer arquivo Markdown.
```bash
# Extrai frontmatter como JSON
node msd-tools.cjs frontmatter get <file> [--field key]
# Atualiza único campo
node msd-tools.cjs frontmatter set <file> --field key --value jsonVal
# Mescla JSON no frontmatter
node msd-tools.cjs frontmatter merge <file> --data '{json}'
# Valida campos obrigatórios
node msd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
```
---
## Comandos de Scaffold
Cria arquivos e diretórios pré-estruturados.
```bash
# Cria template CONTEXT.md
node msd-tools.cjs scaffold context --phase N
# Cria template UAT.md
node msd-tools.cjs scaffold uat --phase N
# Cria template VERIFICATION.md
node msd-tools.cjs scaffold verification --phase N
# Cria diretório de fase
node msd-tools.cjs scaffold phase-dir --phase N --name "phase name"
```
---
## Comandos Init (Carregamento de Contexto Composto)
Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho. `init onboard [--fast] [--text]` retorna, para `/msd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding.
```bash
node msd-tools.cjs init execute-phase <phase>
node msd-tools.cjs init plan-phase <phase>
node msd-tools.cjs init new-project
node msd-tools.cjs init new-milestone
node msd-tools.cjs init onboard [--fast] [--text]
node msd-tools.cjs init quick <description>
node msd-tools.cjs init resume
node msd-tools.cjs init verify-work <phase>
node msd-tools.cjs init phase-op <phase>
node msd-tools.cjs init todos [area]
node msd-tools.cjs init milestone-op
node msd-tools.cjs init map-codebase
node msd-tools.cjs init progress
# Init com escopo de fluxo de trabalho (flag `--ws`)
node msd-tools.cjs init execute-phase <phase> --ws <name>
node msd-tools.cjs init plan-phase <phase> --ws <name>
```
**Tratamento de payloads grandes:** Quando a saída excede ~50KB, o CLI grava em um arquivo temporário e retorna `@file:/tmp/msd-init-XXXXX.json`. Os fluxos de trabalho verificam o prefixo `@file:` e leem do disco:
```bash
INIT=$(node msd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
---
## Comandos de Milestone
```bash
# Arquiva milestone
node msd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]
# Marca requisitos como concluídos
node msd-tools.cjs requirements mark-complete <ids>
# Aceita: REQ-01,REQ-02 ou REQ-01 REQ-02 ou [REQ-01, REQ-02]
```
---
## Habilidades de Agente
Emite o bloco de habilidades para um tipo de agente específico.
```bash
# Emite bloco XML bruto de habilidades (padrão — seguro para expansão de shell)
node msd-tools.cjs agent-skills <agent-type>
# Emite superfície JSON tipada (#455) — { agent_type, block, skills_count }
node msd-tools.cjs agent-skills <agent-type> --json
```
A flag `--json` retorna um objeto IR tipado adequado para consumo estruturado e asserções de teste, enquanto o padrão (sem flag) preserva a saída XML bruta que as expansões de shell de fluxo de trabalho necessitam.
---
## Manifesto de Habilidades
Pré-computa e armazena em cache a descoberta de habilidades para carregamento mais rápido de comandos.
```bash
# Gera manifesto de habilidades (grava em .claude/skill-manifest.json)
node msd-tools.cjs skill-manifest
# Gera com caminho de saída personalizado
node msd-tools.cjs skill-manifest --output <path>
```
Retorna mapeamento JSON de todas as habilidades MSD disponíveis com seus metadados (nome, descrição, caminho de arquivo, dicas de argumentos). Usado pelo instalador e hooks de início de sessão para evitar varreduras repetidas do sistema de arquivos.
---
## Comandos Utilitários
```bash
# Converte texto em slug seguro para URL
node msd-tools.cjs generate-slug "Some Text Here"
# → some-text-here
# Obtém timestamp
node msd-tools.cjs current-timestamp [full|date|filename]
# Conta e lista tarefas pendentes
node msd-tools.cjs list-todos [area]
# Verifica existência de arquivo/diretório
node msd-tools.cjs verify-path-exists <path>
# Agrega todos os dados de SUMMARY.md
node msd-tools.cjs history-digest
# Extrai dados estruturados de SUMMARY.md
node msd-tools.cjs summary-extract <path> [--fields field1,field2]
# Estatísticas do projeto
node msd-tools.cjs stats [json|table]
# Renderização de progresso (legível por humanos)
node msd-tools.cjs progress [json|table|bar]
# Progresso como superfície JSON tipada (#455)
node msd-tools.cjs progress --json
# Conclui uma tarefa
node msd-tools.cjs todo complete <filename> [--dry-run]
# Auditoria UAT — verifica todas as fases em busca de itens não resolvidos
node msd-tools.cjs audit-uat
# Fila de auditoria entre artefatos — verifica `.planning/` em busca de itens de auditoria não resolvidos
node msd-tools.cjs audit-open [--json]
# Migração reversa de um projeto GSD-2 para a estrutura atual (suporta `/msd-import --from-gsd2`)
node msd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# Commit git com verificações de configuração
node msd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> `--no-verify`: Ignora hooks de pré-commit. Usado por agentes executores paralelos durante a execução baseada em ondas para evitar contenção de bloqueio de build (ex.: conflitos de cargo lock em projetos Rust). O orquestrador executa os hooks uma vez após cada onda ser concluída. Não use `--no-verify` durante a execução sequencial — deixe os hooks rodarem normalmente.
> `--files <paths>` **comportamento de staging**: por padrão, `--files` executa `git add -- <path>` para cada arquivo nomeado antes de commitar. Isso sobrescreve qualquer staging por hunk configurado via `git add -p`. Passe `--respect-staged` para ignorar o passo `git add` e commitar apenas o que já está no índice dentro do pathspec solicitado. Se nada estiver staged nesse escopo, o comando retorna `{ committed: false, reason: 'nothing staged' }` sem erro. O `-- <paths>` pathspec final no commit é aplicado em ambos os modos, portanto arquivos staged fora do escopo `--files` nunca são incluídos (invariante #3061).
```bash
# Busca na web (requer chave de API do Brave)
node msd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
## Graphify
Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.planning/graphs/`. Requer `graphify.enabled: true` em `config.json` (consulte a [Referência de Configuração](CONFIGURATION.md#graphify-settings)).
```bash
# Constrói ou reconstrói o grafo de conhecimento
node msd-tools.cjs graphify build
# Pesquisa um termo no grafo
node msd-tools.cjs graphify query <term>
# Exibe atualidade e estatísticas do grafo
node msd-tools.cjs graphify status
# Exibe alterações desde a última construção
node msd-tools.cjs graphify diff
# Grava um snapshot nomeado do grafo atual
node msd-tools.cjs graphify snapshot [name]
```
Ponto de entrada para o usuário: `/msd-graphify` (consulte a [Referência de Comandos](COMMANDS.md#msd-graphify)).
---
## Arquitetura de Módulos
| Módulo | Arquivo | Exportações |
|--------|------|---------|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, utilitários compartilhados, re-exportações de compatibilidade |
| State | `lib/state.cjs` | Todos os subcomandos `state`, `state-snapshot` |
| Phase | `lib/phase.cjs` | CRUD de fase, `find-phase`, `phase-plan-index`, `phases list` |
| Planning Workspace | `lib/planning-workspace.cjs` | Costura de planejamento: `planningDir`, `planningPaths`, roteamento de fluxo de trabalho ativo, `.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | Análise de roadmap, extração de fase, atualizações de progresso |
| Config | `lib/config.cjs` | Leitura/gravação de configuração, inicialização de seção |
| Verify | `lib/verify.cjs` | Todos os comandos de verificação e validação |
| Template | `lib/template.cjs` | Seleção de template e preenchimento de variáveis |
| Frontmatter | `lib/frontmatter.cjs` | CRUD de frontmatter YAML |
| Init | `lib/init.cjs` | Carregamento de contexto composto para todos os fluxos de trabalho |
| Milestone | `lib/milestone.cjs` | Arquivamento de milestone, marcação de requisitos |
| Commands | `lib/commands.cjs` | Diversos: slug, timestamp, todos, scaffold, stats, websearch |
| Model Profiles | `lib/model-profiles.cjs` | Tabela de resolução de perfis |
| UAT | `lib/uat.cjs` | Auditoria UAT/verificação entre fases |
| Profile Output | `lib/profile-output.cjs` | Formatação de perfil do desenvolvedor |
| Profile Pipeline | `lib/profile-pipeline.cjs` | Pipeline de análise de sessão |
| Graphify | `lib/graphify.cjs` | Construção/consulta/status/diff/snapshot do grafo de conhecimento (suporta `/msd-graphify`) |
| Learnings | `lib/learnings.cjs` | Extrai aprendizados de artefatos de fases/SUMMARY (suporta `/msd-extract-learnings`) |
| Audit | `lib/audit.cjs` | Manipuladores de fila de auditoria de fase/milestone; helper `audit-open` |
| MSD2 Import | `lib/gsd2-import.cjs` | Importador de migração reversa de projetos GSD-2 (suporta `/msd-import --from-gsd2`) |
| Intel | `lib/intel.cjs` | Índice de inteligência de código consultável (suporta `/msd-map-codebase --query`) |
---
## Roteamento CLI do Revisor
`review.models.<cli>` mapeia um sabor de revisor para um comando shell invocado pelo fluxo de trabalho de revisão de código. Defina via [`/msd-config --integrations`](COMMANDS.md#msd-config) ou diretamente:
```bash
node msd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node msd-tools.cjs config-set review.models.agy "gemini-3.1-pro-preview"
node msd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node msd-tools.cjs config-set review.models.claude "" # limpa — retorna ao modelo da sessão
```
Os slugs são validados contra `[a-zA-Z0-9_-]+`; slugs vazios ou contendo caminhos são rejeitados. Consulte [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) para a referência completa do campo.
## Tratamento de Segredos
As chaves de API configuradas via `/msd-settings` (`brave_search`, `firecrawl`, `exa_search`) são gravadas em texto simples em `.planning/config.json`, mas são mascaradas (`****<last-4>`) em toda saída de `config-set` / `config-get`, tabela de confirmação e prompt interativo. Consulte `msd-core/bin/lib/secrets.cjs` para a implementação do mascaramento. O próprio arquivo `config.json` é o limite de segurança — proteja-o com permissões do sistema de arquivos e mantenha-o fora do git (`.planning/` está no gitignore por padrão).
---
## Relacionados
- [Comandos](COMMANDS.md)
- [Configuração](CONFIGURATION.md)
- [Arquitetura](ARCHITECTURE.md)
- [índice de documentação](README.md)