Documentação do Labforce Dementor

Visão geral

O Labforce Dementor inspeciona metadados, arquitetura, automações, código, permissões, integrações e sinais operacionais de uma organização Salesforce. O motor produz seus achados e o health score de forma determinística; nenhum provedor de IA é necessário para executar o assessment.

Read-only

Os comandos permitidos são validados por uma allowlist. Deploy, DML e Apex Anonymous são bloqueados.

Rastreável

Os achados mantêm evidências e os artefatos recebem um manifesto de integridade SHA-256.

Local

O processamento e os relatórios ficam no ambiente em que o executável foi iniciado.

Pré-requisitos

Prepare o ambiente local antes da instalação:

Python 3.11 ou superiorConfirme com python3 --version.
Salesforce CLI (sf)Use a versão estável e confirme com sf --version. Consulte a documentação oficial da Salesforce.
Uma org autorizada no Salesforce CLIO usuário deve ter acesso suficiente aos metadados e APIs que serão avaliados.
uv, pipx ou ambiente virtualUse uma instalação isolada para não alterar o Python do sistema.

Instalação

Com uv — recomendado

O uv tool cria um ambiente isolado para o executável e evita alterações no Python do sistema:

TERMINAL

uv tool install labforce-dementor

Disponível oficialmente no PyPI

A versão 4.2.0 já pode ser instalada diretamente do índice público. Consulte também a página oficial do pacote no PyPI.

Com pip em um ambiente virtual

Quando preferir pip, crie primeiro um ambiente virtual. Isso também funciona em instalações protegidas pelo PEP 668:

TERMINAL

python3 -m venv .venv
source .venv/bin/activate
python -m pip install labforce-dementor

Com pipx

O pipx cria um ambiente isolado e expõe o comando globalmente:

TERMINAL

pipx install labforce-dementor

Com o wheel oficial

Na pasta em que o arquivo foi baixado, instale-o diretamente com o uv:

TERMINAL

uv tool install ./labforce_dementor-4.2.0-py3-none-any.whl

Erro externally-managed-environment

Esse erro indica que o Python global é protegido pelo PEP 668. Use uv tool, pipx ou um ambiente virtual. Não use --break-system-packages, pois isso pode danificar o ambiente gerenciado.

Não instale dementor pelo pip

O nome simples dementor pertence a outro projeto no PyPI. Para o produto da Labforce, a distribuição correta é sempre labforce-dementor; depois de instalada, ela disponibiliza o comando curto dementor.

Verifique a instalação

TERMINAL

dementor --version
dementor doctor

A versão publicada atualmente retorna dementor 4.2.0.

O doctor valida o Python, a Salesforce CLI e as dependências locais sem se conectar a uma org.

Conectar uma organização Salesforce

O Dementor usa uma autenticação já mantida pela Salesforce CLI. Abra o fluxo de login e dê um alias claro à org:

PRODUÇÃO OU DEVELOPER ORG

sf org login web --alias MINHA_ORG
sf org display --target-org MINHA_ORG

Para uma sandbox, informe a URL de login correspondente:

SANDBOX

sf org login web \
  --instance-url https://test.salesforce.com \
  --alias MINHA_SANDBOX

Boas práticas de acesso

Use uma identidade aprovada pela organização e conceda apenas as permissões necessárias para leitura. Não copie URLs de autenticação, tokens ou saídas detalhadas do login para tickets e relatórios.

Executar o primeiro diagnóstico

Troque MINHA_ORG pelo alias criado na etapa anterior:

ASSESSMENT COMPLETO

dementor run --target-org MINHA_ORG

Por padrão, os arquivos são gravados em ./assessments/<org>/<data-hora>. Para escolher outra pasta:

SAÍDA PERSONALIZADA

dementor run \
  --target-org MINHA_ORG \
  --output ./relatorios/minha-org

Opções operacionais

--resumeRetoma um checkpoint local compatível após uma interrupção.

--wait-for-deploy 900Espera até 900 segundos por um deploy ou uma validação em andamento antes de pular a recuperação de metadados.

--source-dir force-app/main/defaultAnalisa um snapshot Salesforce local em vez de recuperar os metadados da org.

--profile-dataAtiva, por escolha explícita, estatísticas limitadas de nulidade e cardinalidade. Valores brutos não são persistidos.

Profiling é opt-in

Execute --profile-data somente em uma janela aprovada e quando essas estatísticas forem necessárias. O assessment padrão não solicita essa amostragem.

Entender os relatórios

Um assessment completo gera formatos adequados para análise humana, automação e auditoria.

assessment.htmlRelatório visual para abrir no navegador.

assessment.pdfVersão portátil com a identidade da Labforce.

assessment.mdDocumento em Markdown para revisão técnica.

assessment.jsonSnapshot estruturado usado pelos comandos offline.

charts/Gráficos e ativos visuais do relatório.

integrity-manifest.jsonHashes SHA-256 dos artefatos gerados.

run-manifest.jsonRegistro operacional e localização dos resultados.

Os formatos visuais exibem a marca oficial da Labforce no topo. O rodapé registra Labforce, o sistema Labforce Dementor e a data e hora de geração.

Referência de comandos

Use dementor <comando> --help para ver todos os argumentos disponíveis.

Comando	Finalidade
`doctor`	Valida as dependências locais sem acessar uma org.
`run`	Executa o assessment read-only.
`diff`	Compara dois snapshots `assessment.json`.
`impact`	Analisa o impacto de mudança de um componente.
`drift`	Compara a org capturada com um source tree local.
`tests`	Recomenda testes Apex para componentes impactados.
`knowledge-pack`	Exporta um pacote estruturado para RAG ou agentes.
`policy` / `ci`	Avalia políticas e executa gates offline.
`pr-impact`	Relaciona um diff Git ao grafo de dependências.
`timeline` / `continuous`	Mostra evolução de arquitetura, saúde e riscos.
`sarif`	Exporta achados no formato SARIF 2.1.0.
`criticality`	Calcula um proxy de criticidade estrutural.
`explain`	Explica um componente com base no Digital Twin.
`remediation`	Exporta o plano priorizado de remediação.
`capabilities`	Exporta a matriz de capacidade e evidências.
`simulate`	Simula mudança, remoção ou depreciação sem alterar a org.
`ai-preview`	Prepara o payload sanitizado e o consentimento; não chama o provedor.
`ai-complement`	Gera um complemento consultivo após autorização explícita.

Complemento opcional por IA

O Dementor sempre conclui primeiro o diagnóstico determinístico. Se o usuário quiser uma leitura complementar, ele escolhe o provedor, o modelo exato e os dados autorizados. A chamada só ocorre depois de uma confirmação explícita.

1Gerar préviaSem chamada externa

2Revisar dadosPayload sanitizado

3AutorizarFrase de uso único

4ComplementarRelatório separado

1. Gerar e revisar a prévia

SEM CHAMADA AO PROVEDOR

dementor ai-preview \
  --assessment assessment.json \
  --provider openai \
  --model MODELO_EXATO \
  --scope findings_with_evidence \
  --output ai-consent-preview.json

Revise ai-consent-preview.json e ai-consent-preview-input.json. A prévia informa o conteúdo, o provedor, o modelo, os limites e a frase de autorização.

2. Autorizar e executar

EXECUÇÃO AUTORIZADA

dementor ai-complement \
  --preview ai-consent-preview.json \
  --authorize AUTORIZAR-XXXXXXXX \
  --authorized-by usuario@example.com \
  --credential-source environment \
  --output-dir ai-complement-report

Provedores e credenciais

Os provedores disponíveis são OpenAI, Anthropic, Google Gemini e Ollama local. Na distribuição independente, selecione --credential-source environment e configure somente a variável do provedor escolhido.

Provedor	Variável	Observação
OpenAI	`OPENAI_API_KEY`	Modelo informado explicitamente em `--model`.
Anthropic	`ANTHROPIC_API_KEY`	Modelo informado explicitamente em `--model`.
Google Gemini	`GEMINI_API_KEY`	Modelo informado explicitamente em `--model`.
Ollama	Não se aplica	Endpoint local de loopback por padrão.

EXEMPLO — USE SUA PRÓPRIA CHAVE

# macOS ou Linux
export OPENAI_API_KEY="SUA_CHAVE"

# PowerShell
$env:OPENAI_API_KEY = "SUA_CHAVE"

Quando executado dentro da Labforce Base, o cofre gerenciado é a origem padrão. Informe os escopos da organização e do projeto:

LABFORCE BASE

dementor ai-complement \
  --preview ai-consent-preview.json \
  --authorize AUTORIZAR-XXXXXXXX \
  --authorized-by usuario@example.com \
  --organization minha-organizacao \
  --project meu-projeto

Contrato de consentimento

A autorização fica vinculada ao hash do diagnóstico, ao provedor, ao modelo, aos escopos, ao prompt e ao payload. Ela expira, só pode ser usada uma vez e gera um recibo local. O complemento da IA é consultivo e não altera score, severidade ou achados determinísticos.

Segurança e privacidade

Operação read-onlyO guard bloqueia deploy, DML, Apex Anonymous e comandos fora da allowlist.
Profiling controladoDados de perfil só são consultados com opt-in e os valores brutos não são persistidos.
Orçamento de APIA coleta respeita limites configurados e interrompe caminhos que excedam o orçamento.
Deployment guardUma atividade de deploy pode fazer a recuperação de metadados esperar ou ser ignorada de forma segura.
Segredos fora dos artefatosChaves e tokens não são gravados em prompts, relatórios ou logs pelo fluxo de IA.
Integridade verificávelO manifesto permite confirmar os hashes dos arquivos gerados.

Atualizar ou remover

uv

ATUALIZAR

uv tool upgrade labforce-dementor

REMOVER

uv tool uninstall labforce-dementor

pip

ATUALIZAR

python -m pip install --upgrade labforce-dementor

REMOVER

python -m pip uninstall labforce-dementor

pipx

ATUALIZAR

pipx upgrade labforce-dementor

REMOVER

pipx uninstall labforce-dementor

Solução de problemas

dementor: command not found

Abra um novo terminal e confirme que o diretório de scripts do Python está no PATH. Se usou um ambiente virtual, ative-o. Com pipx, execute pipx ensurepath e abra outro terminal.

Erro externally-managed-environment

Seu Python global é gerenciado pelo uv, Homebrew ou pelo sistema operacional. Instale com uv tool install, pipx ou dentro de um ambiente virtual. Não use --break-system-packages.

O doctor não encontra a Salesforce CLI

Instale ou atualize o executável sf, confirme sf --version no mesmo terminal e execute o diagnóstico novamente.

O alias da org não é reconhecido

Confirme o alias com sf org list. Se a autorização expirou, repita sf org login web --alias MINHA_ORG.

O PDF não foi gerado

Verifique as dependências apontadas pelo dementor doctor. Os arquivos JSON, Markdown e HTML continuam sendo as fontes do assessment; preserve a saída e corrija a dependência local antes de repetir.

Há um deploy ativo na org

Use --wait-for-deploy SEGUNDOS dentro de uma janela aprovada. Sem espera, o Dementor pode pular a recuperação de metadados para evitar conflito.

A autorização de IA expirou ou já foi usada

Gere uma nova prévia, revise novamente o payload e use a nova frase. Autorizações expiradas ou consumidas não devem ser reutilizadas.

A credencial da IA não foi encontrada

Confirme o provedor selecionado e sua variável de ambiente, ou informe os escopos corretos de organização e projeto ao usar o cofre da Labforce Base. Nunca coloque a chave diretamente na linha de comando.

PRÓXIMO PASSO

Pronto para ler o que a sua org revela?

Falar com a Labforce Conhecer o produto

Da instalação aoprimeiro diagnóstico.

Visão geral

Read-only

Rastreável

Local

Pré-requisitos

Instalação

Com uv — recomendado

Com pip em um ambiente virtual

Com pipx

Com o wheel oficial

Verifique a instalação

Conectar uma organização Salesforce

Executar o primeiro diagnóstico

Opções operacionais

Entender os relatórios

Referência de comandos

Complemento opcional por IA

1. Gerar e revisar a prévia

2. Autorizar e executar

Provedores e credenciais

Segurança e privacidade

Atualizar ou remover

uv

pip

pipx

Solução de problemas

Pronto para ler o que a sua org revela?

Da instalação ao
primeiro diagnóstico.