@mcptoolshop/venvkit 0.2.5 → 1.0.0

package/README.md

@@ -1,7 +1,7 @@
-<p align="center">
-  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/venvkit/readme.png" alt="venvkit" width="400">
 </p>
@@ -258,6 +258,17 @@ npm run test       # Run tests
 npm run build      # Build to dist/
 ```
 
+## Security & Data Scope
+
+- **Read-only scanning:** Python executables and pyvenv.cfg are read but never modified
+- **Subprocesses:** spawns `python` with controlled arguments — no shell execution
+- **Network:** optional `--httpsProbe` tests SSL certificates — no other outbound requests
+- **No telemetry** is collected or sent — see [SECURITY.md](SECURITY.md) for the full policy
+
 ## License
 
 MIT
+
+---
+
+Built by [MCP Tool Shop](https://mcp-tool-shop.github.io/)

package/README.pt-BR.md

@@ -1,74 +1,74 @@
-<p align="center">
-  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</a>
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/venvkit/readme.png" alt="venvkit" width="400">
 </p>
-
-# venvkit
-
-> Parte de [MCP Tool Shop](https://mcptoolshop.com)
-
+
+# venvkit
+
+> Parte de [MCP Tool Shop](https://mcptoolshop.com)
+
 <p align="center">
   <a href="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
   <a href="https://mcp-tool-shop-org.github.io/venvkit/"><img src="https://img.shields.io/badge/Landing_Page-live-blue?style=flat-square" alt="Landing Page"></a>
   <a href="https://www.npmjs.com/package/@mcptoolshop/venvkit"><img src="https://img.shields.io/npm/v/@mcptoolshop/venvkit?style=flat-square&color=cb3837" alt="npm version"></a>
 </p>
-
-**Kit de ferramentas de diagnóstico para ambientes virtuais Python em fluxos de trabalho de aprendizado de máquina (ML) para Windows.**
-
-Analisa seu sistema em busca de ambientes Python, diagnostica problemas de saúde (SSL, DLLs, incompatibilidades de ABI, vazamentos de caminho), rastreia o histórico de execução de tarefas, detecta tarefas instáveis e gera um mapa do ecossistema.
-
-## Início rápido em 30 segundos
-
+
+**Kit de ferramentas de diagnóstico para ambientes virtuais Python em fluxos de trabalho de aprendizado de máquina (ML) para Windows.**
+
+Analisa seu sistema em busca de ambientes Python, diagnostica problemas de saúde (SSL, DLLs, incompatibilidades de ABI, vazamentos de caminhos), rastreia o histórico de execução de tarefas, detecta tarefas instáveis e gera um mapa do ecossistema.
+
+## Início rápido em 30 segundos
+
 ```bash
 git clone https://github.com/mcp-tool-shop-org/venvkit && cd venvkit
 npm install && npm run build
 node dist/map_cli.js --root C:\projects --httpsProbe
 # Open .venvkit/venv-map.html in your browser
 ```
-
-## Recursos
-
-- **doctorLite** - Verificação rápida de saúde para qualquer interpretador Python
-- Verificação SSL/TLS
-- Falhas ao carregar DLLs (comum com PyTorch/CUDA)
-- Incompatibilidades de ABI (ARM vs x86)
-- Verificações de sanidade do pip
-- Detecção de vazamentos de user-site e PYTHONPATH
-
-- **scanEnvPaths** - Descobre todos os ambientes Python no seu sistema
-- Encontra venvs, ambientes conda, versões pyenv, interpretadores base
-- Profundidade e filtragem configuráveis
-
-- **mapRender** - Visualize seu ecossistema Python
-- Saída JSON para uso programático
-- Diagramas Mermaid para documentação
-- Agrupamento de interpretadores base com análise de raio de impacto
-- Visualização de roteamento de tarefas
-
-- **runLog** - Rastreia o histórico de execução de tarefas
-- Formato JSONL somente para anexar
-- Registra qual ambiente executou qual tarefa
-- Captura sucesso/falha com classificação de erro
-
-- **taskCluster** - Agrupa execuções de tarefas por assinatura
-- Detecção de tarefas instáveis (passagem/falha inconsistente)
-- Detecção de instabilidade dependente do ambiente
-- Identificação de pontos críticos de falha
-- Análise de contágio (causas-raiz compartilhadas)
-
-## Instalação
-
+
+## Recursos
+
+- **doctorLite** - Verificação rápida de saúde para qualquer interpretador Python
+- Verificação SSL/TLS
+- Falhas ao carregar DLLs (comum com PyTorch/CUDA)
+- Incompatibilidades de ABI (ARM vs x86)
+- Verificações de integridade do pip
+- Detecção de vazamentos de user-site e PYTHONPATH
+
+- **scanEnvPaths** - Descobre todos os ambientes Python no seu sistema
+- Encontra venvs, ambientes conda, versões pyenv, interpretadores base
+- Profundidade e filtragem configuráveis
+
+- **mapRender** - Visualize seu ecossistema Python
+- Saída JSON para uso programático
+- Diagramas Mermaid para documentação
+- Agrupamento de interpretadores base com análise de raio de impacto
+- Visualização de roteamento de tarefas
+
+- **runLog** - Rastreia o histórico de execução de tarefas
+- Formato JSONL somente para anexar
+- Registra qual ambiente executou qual tarefa
+- Captura sucesso/falha com classificação de erro
+
+- **taskCluster** - Agrupa execuções de tarefas por assinatura
+- Detecção de tarefas instáveis (passagem/falha inconsistente)
+- Detecção de instabilidade dependente do ambiente
+- Identificação de pontos críticos de falha
+- Análise de contágio (causas-raiz compartilhadas)
+
+## Instalação
+
 ```bash
 npm install
 npm run build
 ```
-
-## Uso da CLI
-
+
+## Uso da CLI
+
 ```bash
 # Scan current directory and generate ecosystem map
 node dist/map_cli.js
@@ -82,33 +82,33 @@ node dist/map_cli.js --runlog .venvkit/runs.jsonl
 # Output options
 node dist/map_cli.js --out ./output --minScore 50 --strict --httpsProbe
 ```
-
-### Opções da CLI
-
-| Flag | Descrição |
-| ------ | ------------- |
-| `--root, -r` | Diretório a ser analisado (pode especificar vários) |
-| `--out` | Diretório de saída (padrão: `.venvkit`) |
-| `--maxDepth` | Profundidade máxima do diretório a ser analisado (padrão: 5) |
-| `--strict` | Habilita verificações de modo estrito |
-| `--httpsProbe` | Testa a conectividade HTTPS |
-| `--minScore` | Filtra ambientes abaixo desta pontuação de saúde |
-| `--concurrency` | Verificações paralelas (padrão: número de núcleos da CPU) |
-| `--runlog` | Caminho para o registro de execução da tarefa (JSONL) |
-| `--no-tasks` | Ignora a visualização da tarefa |
-
-### Saídas
-
-| File | Descrição |
-| ------ | ------------- |
-| `venv-map.json` | Dados completos do gráfico (nós, arestas, resumo) |
-| `venv-map.mmd` | Fonte do diagrama Mermaid |
-| `venv-map.html` | Visualizador interativo |
-| `reports.json` | Relatórios raw do doctorLite |
-| `insights.json` | Recomendações acionáveis |
-
-## Uso programático
-
+
+### Opções da CLI
+
+| Flag | Descrição |
+|------|-------------|
+| `--root, -r` | Diretório a ser analisado (pode especificar vários) |
+| `--out` | Diretório de saída (padrão: `.venvkit`) |
+| `--maxDepth` | Profundidade máxima do diretório a ser analisado (padrão: 5) |
+| `--strict` | Habilita verificações de modo estrito |
+| `--httpsProbe` | Testa a conectividade HTTPS |
+| `--minScore` | Filtra ambientes abaixo desta pontuação de saúde |
+| `--concurrency` | Verificações paralelas (padrão: número de CPUs) |
+| `--runlog` | Caminho para o registro de execução da tarefa (JSONL) |
+| `--no-tasks` | Ignora a visualização da tarefa |
+
+### Saídas
+
+| Arquivo | Descrição |
+|------|-------------|
+| `venv-map.json` | Dados completos do gráfico (nós, arestas, resumo) |
+| `venv-map.mmd` | Fonte do diagrama Mermaid |
+| `venv-map.html` | Visualizador interativo |
+| `reports.json` | Relatórios raw do doctorLite |
+| `insights.json` | Recomendações acionáveis |
+
+## Uso Programático
+
 ```typescript
 import { doctorLite, scanEnvPaths, mapRender, readRunLog } from 'venvkit';
 
@@ -143,11 +143,11 @@ const { graph, mermaid, insights } = mapRender(reports, runs, {
   includeHotEdgeLabels: true,
 });
 ```
-
-## Esquema do Registro de Tarefas
-
-Rastreie as execuções de tarefas anexando eventos a um arquivo JSONL:
-
+
+## Esquema do Registro de Tarefas
+
+Rastreie as execuções de tarefas anexando eventos a um arquivo JSONL:
+
 ```typescript
 import { appendRunLog, newRunId } from 'venvkit';
 
@@ -172,11 +172,11 @@ await appendRunLog('.venvkit/runs.jsonl', {
   },
 });
 ```
-
-## Agrupamento de Tarefas
-
-Quando você tem muitas execuções de tarefas, o venvkit as agrupa por assinatura:
-
+
+## Agrupamento de Tarefas
+
+Quando você tem muitas execuções de tarefas, o venvkit as agrupa por assinatura:
+
 ```typescript
 import { clusterRuns, isFlaky, getFailingEnvs } from 'venvkit';
 
@@ -192,11 +192,11 @@ for (const c of clusters) {
   }
 }
 ```
-
-## Esquema do Gráfico
-
-A saída do `mapRender` segue um esquema JSON estável:
-
+
+## Esquema do Gráfico
+
+A saída do `mapRender` segue um esquema JSON estável:
+
 ```typescript
 type GraphJSONv1 = {
   version: '1.0';
@@ -217,47 +217,58 @@ type GraphJSONv1 = {
   edges: GraphEdge[];
 };
 ```
-
-### Tipos de Nós
-
-| Type | Descrição |
-| ------ | ------------- |
-| `base` | Interpretador Python base (por exemplo, `C:\Python311`) |
-| `venv` | Ambiente virtual |
-| `task` | Assinatura da tarefa (execuções agrupadas) |
-
-### Tipos de Arestas
-
-| Type | Descrição |
-| ------ | ------------- |
-| `USES_BASE` | Relacionamento venv → base |
-| `ROUTES_TASK_TO` | Roteamento de tarefa → ambiente |
-| `FAILED_RUN` | Falha de tarefa → ambiente (tracejado em Mermaid) |
-
-## Códigos de Erro
-
-| Code | Severidade | Descrição |
-| ------ | ---------- | ------------- |
-| `SSL_BROKEN` | bad | O módulo SSL falha ao importar |
-| `CERT_STORE_FAIL` | warn | A verificação do certificado HTTPS falha |
-| `DLL_LOAD_FAIL` | bad | A carga da DLL de extensão nativa falha |
-| `ABI_MISMATCH` | bad | Incompatibilidade binária (ARM/x86) |
-| `PIP_MISSING` | warn | pip não disponível |
-| `PIP_CHECK_FAIL` | warn | Conflitos de dependência detectados |
-| `USER_SITE_LEAK` | warn | Pacotes do usuário habilitados no ambiente virtual. |
-| `PYTHONPATH_INJECTED` | warn | Variável de ambiente PYTHONPATH definida. |
-| `ARCH_MISMATCH` | bad | Versão de 32 bits do Python quando a versão de 64 bits é necessária. |
-| `PYVENV_CFG_INVALID` | warn | Arquivo pyvenv.cfg corrompido ou ausente. |
-
-## Desenvolvimento
-
+
+### Tipos de Nós
+
+| Tipo | Descrição |
+|------|-------------|
+| `base` | Interpretador Python base (por exemplo, `C:\Python311`) |
+| `venv` | Ambiente virtual |
+| `task` | Assinatura da tarefa (execuções agrupadas) |
+
+### Tipos de Arestas
+
+| Tipo | Descrição |
+|------|-------------|
+| `USES_BASE` | Relacionamento venv → base |
+| `ROUTES_TASK_TO` | Roteamento de tarefa → ambiente |
+| `FAILED_RUN` | Falha de tarefa → ambiente (tracejado em Mermaid) |
+
+## Códigos de Erro
+
+| Código | Severidade | Descrição |
+|------|----------|-------------|
+| `SSL_BROKEN` | bad | O módulo SSL falha ao importar |
+| `CERT_STORE_FAIL` | warn | A verificação do certificado HTTPS falha |
+| `DLL_LOAD_FAIL` | bad | Falha ao carregar DLL de extensão nativa |
+| `ABI_MISMATCH` | bad | Incompatibilidade binária (ARM/x86) |
+| `PIP_MISSING` | warn | pip não disponível |
+| `PIP_CHECK_FAIL` | warn | Conflitos de dependência detectados |
+| `USER_SITE_LEAK` | warn | user-site-packages habilitado no venv |
+| `PYTHONPATH_INJECTED` | warn | Variável de ambiente PYTHONPATH definida |
+| `ARCH_MISMATCH` | bad | Python de 32 bits quando 64 bits são necessários |
+| `PYVENV_CFG_INVALID` | warn | pyvenv.cfg corrompido ou ausente |
+
+## Desenvolvimento
+
 ```bash
 npm install
 npm run typecheck  # Type check
 npm run test       # Run tests
 npm run build      # Build to dist/
 ```
-
-## Licença
-
-MIT.
+
+## Segurança e Escopo de Dados
+
+- **Leitura apenas:** Os executáveis Python e o arquivo pyvenv.cfg são lidos, mas nunca modificados.
+- **Subprocessos:** Inicia o `python` com argumentos controlados — sem execução via shell.
+- **Rede:** A opção `--httpsProbe` (opcional) testa certificados SSL — não são feitas outras requisições de saída.
+- **Nenhuma telemetria** é coletada ou enviada — consulte o arquivo [SECURITY.md](SECURITY.md) para a política completa.
+
+## Licença
+
+MIT
+
+---
+
+Criado por [MCP Tool Shop](https://mcp-tool-shop.github.io/)