Communitygithub.com

sethjuarez/auditaur

Auditaur como superfície de diagnóstico inicial para depuração de aplicativos Tauri.

O que é auditaur?

O Auditaur é uma ferramenta de diagnóstico e depuração projetada especificamente para aplicativos construídos com o framework Tauri (Rust + WebView). Ele atua como observador do aplicativo, fornecendo telemetria estruturada, logs, rastreamento de IPC, captura de snapshots e screenshots, e uma ponte de automação nativa (drive bridge) para interações programáticas com a interface do usuário. O Auditaur suporta múltiplos modos de operação: anexação passiva a um aplicativo já em execução ou execução em modo wrapper para cenários de automação e integração contínua. Sua interface é orientada a comandos de linha de terminal e saída JSON, sendo ideal para uso por agentes de IA (como Claude Code, Cursor, Codex) que precisam depurar, inspecionar e testar aplicativos Tauri de forma confiável. O fluxo típico envolve verificar a prontidão do aplicativo (readiness), inspecionar telemetria, e, quando necessário, dirigir a interface através da ponte nativa do Tauri. O Auditaur também gerencia adequadamente a limpeza de processos e sessões, e suporta "portões humanos" (human gates) para fluxos que exigem autorização manual, como OAuth ou aprovação de permissões.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add sethjuarez/auditaur

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Fluxo de trabalho de depuração Auditaur

Use o Auditaur como a primeira superfície de diagnóstico para depuração de aplicativos Tauri. Prefira JSON legível por máquinas ao atuar como um agente. O modelo mental canônico é: o Auditaur observa o aplicativo; ele não substitui o comando de desenvolvimento normal do aplicativo.

Mapa de intenções

Traduza frases comuns do usuário para o fluxo de trabalho Auditaur apropriado:

Frase do usuárioInterpretação do agente
"observar o aplicativo"Anexar ao aplicativo já em execução e monitorar a prontidão.
"iniciar com Auditaur" / "Auditaur inicia o aplicativo"Executar auditaur start quando .auditaur/config.json existir; caso contrário, iniciar o comando normal do aplicativo sob observação do Auditaur com debug run -- <comando normal>.
"depurar o aplicativo com Auditaur"Verificar a prontidão primeiro, depois inspecionar logs/linha do tempo/rastros/IPC.
"dirigir o aplicativo" / "clicar no aplicativo"Exigir a ponte de direção nativa do Tauri, então usar auditaur drive.
"executar um drill" / "teste de fumaça no aplicativo"Executar auditaur drill para o drill padrão configurado, ou auditaur drill <nome> para um drill nomeado.
"aprovação manual" / "portão humano" / "consentimento OAuth"Usar um portão de script de drill para que a sessão do aplicativo permaneça fixa enquanto a ação humana é concluída.

Preserve o comando de inicialização normal do aplicativo. Prefira o fluxo simples configurado no repositório quando disponível:

auditaur start
auditaur drill
auditaur inspect
auditaur stop

Esses comandos leem .auditaur/config.json e compartilham .auditaur/session.json por padrão, para que os agentes não precisem de wrappers personalizados para sondagem de prontidão, IDs de sessão, caminhos de banco de dados ou limpeza de processos.

Use auditaur start --json quando um agente precisar de saída de inicialização legível por máquina. Ele emite um objeto JSON final com a sessão exata do aplicativo, processo, seletores, caminho do arquivo de sessão e quaisquer portas nomeadas geradas. auditaur stop para a árvore de processos gravada e remove o arquivo de sessão após a limpeza, para que comandos subsequentes não tenham como alvo uma sessão morta.

Prontidão primeiro

Antes de ler logs ou dirigir a interface do usuário, estabeleça o que está pronto:

auditaur debug --app <nome-do-app> --json status

Para um aplicativo em execução, monitore até que a telemetria principal esteja pronta:

auditaur debug --app <nome-do-app> --active --json watch --until-ready --timeout-seconds 120

Se a tarefa exigir telemetria de frontend, adicione --require-frontend. Se a tarefa exigir ações de seletor WebView, use a ponte de direção no aplicativo do Auditaur: habilite initAuditaur({ driveBridge: true }) em exatamente um WebView de depuração/teste por sessão do Auditaur e adicione --require-drive-bridge às observações de prontidão.

npm run tauri dev
auditaur debug --app <nome-do-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120

No Windows PowerShell:

npm run tauri dev
auditaur debug --app <nome-do-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120

O Auditaur drive usa a ponte de direção nativa do Tauri no aplicativo. O aplicativo deve habilitar explicitamente initAuditaur({ driveBridge: true }) em exatamente um WebView de depuração/teste por sessão do Auditaur; em seguida, auditaur drive envia requisições limitadas através dessa ponte.

Iniciando o aplicativo

Prefira o modo de anexação por padrão: deixe o desenvolvedor, IDE, servidor de desenvolvimento Tauri ou terminal existente controlar a inicialização do aplicativo, então use auditaur debug watch para observar a prontidão. Isso preserva o ambiente normal do usuário, depurador, hot reload e saída do terminal.

Use o modo wrapper apenas quando o agente ou um script de teste precisar controlar uma execução repetível. O modo wrapper ainda deve iniciar o aplicativo através de seu comando normal; o Auditaur observa esse processo em vez de substituir o sistema de inicialização do aplicativo.

CenárioModo preferido
Depuração local humanaAnexar ao aplicativo já em execução
IDE/depurador/fluxo de desenvolvimento Tauri já em execuçãoAnexar
Agente precisa de uma execução de validação ponta a pontaWrapper
Dogfood ou teste de fumaça local tipo CIWrapper

Se o agente deve iniciar o aplicativo, envolva o comando existente:

auditaur start

auditaur start usa .auditaur/config.json, relata prontidão, escreve .auditaur/session.json e intencionalmente deixa o aplicativo em execução depois que ele fica pronto. Se a configuração declarar portas nomeadas, start reserva portas locais aleatórias, expande placeholders {{port:nome}} no comando, define variáveis de ambiente de porta configuradas e registra as portas escolhidas no arquivo de sessão e na saída JSON. Se nenhuma configuração existir ainda, use a forma de nível inferior:

auditaur debug --app <nome-do-app> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev

debug run relata prontidão e intencionalmente deixa o aplicativo em execução depois que ele fica pronto. Quando --app é fornecido, ele ignora registros de descoberta correspondentes que existiam antes da inicialização, aguarda a nova sessão do Auditaur e fixa a prontidão àquela sessão/banco de dados/pid exatos. Use --write-session <caminho> para inicialização controlada pelo agente, para que comandos posteriores possam ler sessionId, instanceId, pid, databasePath e os arrays de argumentos de seletor gerados, em vez de adivinhar com --active ou --latest. Limpe o processo do aplicativo iniciado com auditaur stop quando a validação estiver concluída.

Interpretando prontidão

Inspecione o array stages:

  • app_discovery: O arquivo de descoberta do Auditaur existe.
  • heartbeat: O heartbeat do aplicativo está atualizado.
  • telemetry_database: O banco de dados SQLite existe e o esquema é validado.
  • session: Uma linha de sessão é consultável.
  • window: A telemetria de janela do Tauri existe.
  • backend_telemetry: Logs, spans ou linhas de janela do backend/plugin existem.
  • frontend_telemetry: Logs/erros/IPC/eventos do frontend existem; necessário apenas com --require-frontend.
  • drive_bridge: O status da ponte de direção nativa do Tauri no aplicativo existe e tem um heartbeat atualizado; necessário apenas com --require-drive-bridge.
  • cdp_endpoint: Prontidão do endpoint legado de depuração do navegador; verificado apenas quando explicitamente solicitado.

Se a prontidão for falsa, siga as mensagens de estágio e hints em vez de adivinhar pela saída do terminal.

Dirigindo o WebView

Inspecione a ponte de direção nativa do Tauri antes de modificar o aplicativo:

auditaur drive --app <nome-do-app> --active --json inspect

Se a seleção de alvo for necessária, use o alvo da ponte:

auditaur drive --app <nome-do-app> --active --json click --target auditaur-bridge --selector '<css>'

Use ações somente leitura primeiro quando possível:

auditaur drive --app <nome-do-app> --active --json exists --selector '<css>'
auditaur drive --app <nome-do-app> --active --json text --selector '<css>'
auditaur drive --app <nome-do-app> --active --json snapshot --selector body --output failure.json
auditaur drive --app <nome-do-app> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json

Revise os artefatos de snapshot antes de compartilhá-los; eles podem conter texto do DOM, URLs ou outro conteúdo sensível.

Para entrada de texto, use fill quando um setter direto de valor no DOM mais eventos input/change for suficiente. Use type quando uma entrada ou textarea controlada por framework precisar de inserção de texto focada:

auditaur drive --app <nome-do-app> --active --json type --selector 'textarea' --value 'olá' --visible-only

Prefira --visible-only (ou --visible) com ações de seletor (wait, exists, text, click, fill, type, hover, select, check e uncheck) ao validar modais, overlays de foco ou shells em tela cheia que deixam DOM oculto duplicado para trás.

Se drive inspect relatar bridge.status inativo, habilite driveBridge no frontend. Uma vez ativo, use wait, exists, text, click, fill, type, press, hover, select, check, uncheck, evaluate, snapshot e screenshot através da ponte nativa do Tauri. Screenshots da ponte tentam primeiro a captura nativa do WebView (screenshotBackend=tauri_native_webview_snapshot) para pixels do WebView sem oclusão; screenshots de seletor recortam essa imagem do WebView e relatam screenshotScope=selector mais selectorRect. Se a captura do WebView falhar, o Auditaur recorre à captura nativa da janela (screenshotBackend=tauri_native_window_xcap) e depois ao PNG de resumo de texto do DOM (screenshotBackend=bridge_dom_summary_canvas) com metadados de erro. evaluate executa JavaScript arbitrário no WebView, portanto, mantenha a ponte restrita a sessões de desenvolvimento/teste. Se a ponte estiver inativa, use a telemetria do Auditaur (timeline, ipc, traces, explain) como fonte de verdade e emparelhe-a com automação de Acessibilidade apenas quando a entrada manual da interface do usuário precisar ser simulada.

Compatibilidade legada: --cdp-port pode aparecer em comandos mais antigos, mas auditaur drive o ignora. Use frases positivas para comandos de direção: diga que eles usam a ponte de direção nativa do Tauri.

Inspecionando telemetria

Após a prontidão, use comandos de leitura estruturada:

auditaur apps --json
auditaur sessions --json
auditaur logs --json
auditaur errors --json
auditaur ipc --json
auditaur events --json
auditaur traces --json
auditaur timeline --json
auditaur explain --json

Prefira --session <id>, --db <caminho>, --active, --latest, --pid ou --instance-id quando houver sessões obsoletas ou múltiplas.

Portões humanos em drills

Use portões humanos de drill para fluxos de trabalho que exigem ação humana real, preservando a mesma sessão de aplicativo fixa: aprovação OAuth/código de dispositivo, prompts de permissão do SO, elevação de instalador, transferências para navegador externo, permissões de câmera/microfone, chaves de segurança de hardware ou qualquer fluxo onde um agente deva pausar em vez de simular entrada sensível à confiança.

Adicione portões em um script de drill e execute o drill com --script <caminho>:

{
  "gates": [
    {
      "name": "Aprovar login do GitHub",
      "instructions": "Complete a aprovação do código de dispositivo do GitHub no aplicativo ou navegador e retorne aqui.",
      "selector": "#status-card",
      "expectText": "Conectado",
      "manualContinue": true,
      "timeoutMs": 300000,
      "choices": [
        { "id": "done", "label": "Concluído", "outcome": "continue" },
        { "id": "blocked", "label": "Bloqueado", "outcome": "fail" }
      ]
    }
  ]
}

Os portões humanos são executados depois que o Auditaur iniciou e fixou a nova sessão do aplicativo e atingiu a prontidão, mas antes da coleta de evidências de seletor/texto/erro/IPC/explicação. Não reinicie o aplicativo nem mude para uma sessão diferente durante o portão; o objetivo é manter as evidências pré-portão e pós-portão anexadas à mesma sessão/banco de dados/pid. Os portões podem ser esperas monitoradas apenas por seletor, continuações manuais, escolhas com resultados continue/retry/skip/fail/abort, entradas e dicas de área de transferência. Entradas sensíveis e valores da área de transferência são ocultados nos relatórios de drill por padrão, mas o JSON de resposta do portão temporário local pode conter brevemente valores de entrada brutos até que o drill os consuma e remova.

Quando um portão exigir uma resposta manual, o Auditaur também publica uma requisição local à sessão junto ao banco de dados da sessão fixada. Agentes podem listar e responder a essas requisições através de MCP:

auditaur mcp

Use list_pending_human_gates para encontrar portões pendentes e respond_human_gate com o requestId, choiceId opcional, inputs opcionais e um valor responder claro. Execute o servidor MCP com o mesmo diretório de dados do Auditaur do drill para que ele possa ver os arquivos de requisição locais da sessão. Se a extensão do canvas do Copilot estiver instalada com auditaur init extension, abra o canvas auditaur-human-gate para o portão pendente para que o usuário receba um cartão de ação e possa clicar em uma resposta. A entrada ENTER/escolha no terminal permanece como fallback quando nenhum cliente MCP ou canvas está disponível.

Padrões comuns de falha

  • Nenhum arquivo de descoberta: o aplicativo ainda está compilando, não foi iniciado ou o plugin Auditaur não foi registrado.
  • Banco de dados não legível/esquema inválido: o aplicativo foi inicializado parcialmente ou o diretório de dados está errado.
  • Nenhuma telemetria de frontend: a API do frontend não foi inicializada, nenhuma ação do frontend foi disparada ou a exportação falhou na interface do usuário.
  • Ponte de direção inativa: habilite initAuditaur({ driveBridge: true }) em exatamente um WebView de depuração/teste; caso contrário, use telemetria mais fallback de Acessibilidade.
  • Portão humano pendente: não o ignore com estado de aplicativo sintético. Apresente as instruções do portão ao usuário, responda através do caminho canvas/MCP/terminal e continue a coleta de evidências na mesma sessão fixada.
  • Ambiguidade de alvo: use --target auditaur-bridge; se várias sessões corresponderem, desambiguize com --session-id, --instance-id, --pid, --latest ou --active.
  • Contaminação da saída JSON: use debug run --json de um Auditaur CLI atual; a saída de inicialização do processo filho não deve aparecer nas linhas JSON.

Loop de validação

Para alterações de alta confiança:

  1. Execute os testes/builds relevantes.
  2. Inicie ou anexe com auditaur debug.
  3. Execute o auditaur drill configurado; se ele publicar um portão humano, apresente-o através do caminho de resposta canvas/MCP/terminal em vez de substituir a ação manual.
  4. Dirija um caminho representativo da interface do usuário através da ponte nativa do Tauri quando a cobertura de interface for necessária.
  5. Verifique novamente debug status --require-frontend quando a telemetria do frontend for importante.
  6. Inspecione timeline e explain.
  7. Limpe os processos de aplicativo iniciados e diretórios de telemetria temporários.

Habilidades Relacionadas