io.github.silex-tec/silex

Create a workspace and trigger the ingestion scan in background. Quando usar: primeiro passo pra analisar um repositório novo (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``get_workspace_stats`` (poll até ``scan_status=completed``); se não souber o ``workspace_id``, ``list_workspaces`` primeiro. Two modes, both returning immediately after the workspace is registered (BEFORE scan completes). In both cases the scan (chunking, Neo4j/SQLite mirror, Qdrant, communities, semantic labeling) runs in a daemon thread — check progress with ``get_workspace_stats(workspace_id)``. Mode ``git`` (default) — multi-repo CLONE: Clones each repo (reusing existing clones for the same URL+branch) and registers one ``Repo`` per spec. Wraps the same engine as POST /api/workspaces. Mode ``local`` (EXT-ZEROCONF-2 #1040) — attach IN-PLACE, no clone/copy: Registers ``local_path`` as the workspace source via ``create_workspace_with_source`` and scans the directory WHERE IT IS (zero clone, zero copy). This is the Jornada B path: the "Analisar este repositório" button in the Extension analyses the repo the user already has open. ``repos`` is IGNORED in this mode.

Generate a human-readable Markdown domain report for sharing with QA, functional analysts and tech leads. Quando usar: fechamento do fluxo de exploração — consolidar entidades/rules/FSMs/workflows num relatório compartilhável (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: nenhum obrigatório; para enriquecer com LLM primeiro, confira ``silex.llm_provider.status`` e rode de novo com ``enrich_with_llm=True``. Runs the full extraction pipeline, then renders a report with: - Summary (entities, rules, state machines, workflows) - Entity table with fields, relationships, PKs - State machine diagrams with transitions - Business rules table (with 🔧 heuristic / 🤖 llm badges) - Enums table - Workflow summaries - Gap analysis with severity emojis - Recommended next steps

Hierarchical code communities (Leiden) with members + labels — tier-aware. Quando usar: ver o mapa navegável do codebase (comunidades hierárquicas com labels) depois do scan completo (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``get_structural_findings`` (achados sem LLM) ou ``silex.community.code_pack`` pra ler o código de uma comunidade específica. J1-MAPA-1 (#1077): fonte do MAPA navegável do Domain Explorer no free-tier. Delega ao leitor canônico único ``fetch_communities_with_members`` (DOGFOOD-2 #678), que resolve o tier: no free lê ``.silex/workspace.db`` (SQLite), no pro/enterprise lê Postgres — SHAPE IDÊNTICO nos dois. Ao contrário de ``get_communities`` (Postgres-only, shape achatado), devolve a hierarquia completa com a MESMA forma anexada por ``generate_domain_jsons`` no campo ``communities``: ``id, label, level, parent_id, algorithm, cohesion, bridge_nodes, members``. Ordem estável (supers por size desc; cada sub logo após o pai). Lista vazia quando o workspace não tem community detection rodada — o consumidor trata como "sem mapa" (orientação #1058), nunca mapa fantasma.

Batch-fetch rules from the materialized ``business_logic.json``. Quando usar: resolver ``linked_rule_ids`` (de um step de workflow ou de ``silex.business_logic.submit``) em rule dicts completos, num round-trip (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``generate_domain_report`` pra visão consolidada do domínio. Sprint 2026-04-17. Used by the Workflow Viewer to resolve ``step.linked_rule_ids`` into full rule dicts in a single round-trip (avoids N calls to ``get_operation_detail`` per workflow).

Structural findings — pontes, hubs e áreas órfãs do grafo local (sem LLM). Quando usar: depois do mapa (``get_code_communities``), pra achados estruturais objetivos (pontes/hubs/órfãos) sem gastar LLM (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``silex.community.code_pack`` pra aprofundar numa comunidade específica. ACHADOS-1 (#1114): a fonte da seção **Achados** do Domain Explorer (irmã do mapa J1-MAPA-1 #1077). Fina por cima do service ``compute_structural_findings``, que deriva os três achados dos MESMOS dados do mapa (comunidades de código + arestas ``code_references``) via os leitores canônicos tier-aware — free lê o espelho SQLite, pro/enterprise Postgres/ Neo4j. NÃO recomputa comunidades nem escreve no grafo. Shape: ``{workspace_id, bridges, hubs, orphan_areas, hardcoded_secrets, shared_literals, clone_families, clone_families_total, clone_families_capped, dead_code_candidates, risk_markers, config_usage, state_contradictions}``. ``hardcoded_secrets`` (SENSOR-SECRET-1 #1200) é aditivo: connection string ``Password=``/``Pwd=`` ou api key/token/secret literal em código de aplicação, com âncora ``file``/``line`` e valor SEMPRE mascarado (``masked_value``, nunca o segredo em claro). ``shared_literals`` (SENSOR-LIT-1 #1201) é aditivo: literal distintivo (≥6 chars, não-rota/SQL/path/formato) compartilhado entre arquivos de ≥2 comunidades ou 2 linguagens vira achado ``shared_literal`` com âncoras de TODOS os arquivos envolvidos (padrão golden: ``FP_events`` PHP×JS do SuiteCRM) — literal trivial/único/de alta frequência nunca vira achado. ``clone_families`` (SENSOR-CLONE-1 #1202) é aditivo: bloco de código idêntico (normalizado, janela de ≥5 linhas significativas) repetido em ≥2 arquivos de aplicação vira UMA família ``clone_family`` com TODOS os membros ancorados (``file``/``line_start``/``line_end`` por membro) — nunca N achados soltos pro mesmo clone. Cap de 100 famílias (as maiores primeiro) declarado via ``clone_families_total``/``clone_families_ca…

Get overview stats for a workspace: classes, edges, communities, languages. ``language`` (SCAN-IGNORE-1 #1329, mesmo contrato stateless de ``generate_domain_report``): idioma da linha honesta ``vendor_generated`` — ``"en"`` (default) ou ``"pt-br"``. Idioma desconhecido devolve erro estruturado (``normalize_language``), nunca fallback silencioso. Quando usar: poll depois de ``create_workspace`` até ``scan_status`` virar ``completed`` (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``get_code_communities`` (mapa) quando o scan terminar. Tier-aware (STATS-TIER-1 #1057). Este é o elo do poll do botão de 1 clique: o free-tier não tem Neo4j instalado, então o ramo pago (que consulta o grafo) importava ``neo4j`` incondicionalmente e o poll morria com ``No module named 'neo4j'`` mesmo com o scan já completo. - Tier ``free``: contagens vêm do espelho SQLite do workspace (``workspace.db`` — chunks/edges/comunidades, ONBOARD-2 #667 e DOGFOOD-2 #678), SEM tocar Neo4j (o import de ``neo4j`` só acontece no ramo pago, padrão lazy #669/#1059). Todo campo do shape tem fonte real no mirror — nenhum é hardcoded; campos sem dado no mirror caem para 0/[] honestamente (mirror vazio → contagens zeradas, não erro). - Tier pago (``pro``/``enterprise``/``legacy`` explícito): comportamento byte-idêntico ao histórico (Neo4j para classes/edges/ linguagens + Postgres para comunidades). Desde REFA-1B (#1043) o mundo pesado é DECLARADO — ausência de ``SILEX_TIER`` resolve free. O shape de resposta é IDÊNTICO entre tiers: ``{workspace_id, classes, edges, communities, languages, scan_status, heartbeat_age_seconds, scan_phase, vendor_generated_excluded, next_action}``. J1-DONE-1 (#1069): ``scan_status`` (registry de workspaces, mesma coluna nos dois tiers — ``scanning``/``completed``/``error``/``pending``) é o sinal de "pipeline COMPLETO" que o poll do botão de 1 clique passou a exigir; ``classes > 0`` só prova o fim do chunking (existe minutos antes de linking/Leiden/ co…

List all registered workspaces, most recently updated first. Quando usar: descobrir workspaces já existentes antes de repetir ``create_workspace`` (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``get_workspace_stats(workspace_id)`` com o id escolhido. Reads the local registry in-process (same tier-aware path as ``create_workspace`` — no HTTP, no running API required). Read-only — no side effects. Use this before ``create_workspace`` or any workspace-scoped tool to let the caller pick an existing workspace by name instead of requiring a raw UUID. Returns: Raw JSON text: a list of WorkspaceRead objects, each with ``id`` (UUID), ``name``, ``description``, ``scan_status``, ``repos`` and timestamps. Capped at 100 workspaces by the underlying route.

Persiste **rules extraídas pelo LLM do cliente** (com provenance) (#675). Quando usar: depois de ``silex.community.code_pack`` — submeter as rules que o LLM do cliente extraiu do código lido (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``silex.contract.fact.generate`` pra consolidar o escopo, ou ``generate_domain_report`` pra visão completa do domínio. Fecha o loop da arqueologia client-orchestrated (ONBOARD-6): recebe as rules que o **LLM do cliente** extraiu do ``code_pack``, **valida a evidência** e as **persiste** no ``business_logic.json`` materializado — shape consumido por ``silex.contract.fact.generate`` (passa a montar o ``fact_contract`` com **rules reais**, não fixture). Trava não-negociável: **rule sem evidência é alucinação**. Cada rule exige ``provenance`` — ``class_name`` (símbolo), ``source_file`` (arquivo) e ``line_start`` **ou** ``evidence`` (localização/trecho). Rule sem isso é **rejeitada** (erro estruturado) e **nada é persistido** (atômico). As rules entram como ``proposed`` (camada 1.5 — fato candidato, nunca ground-truth silencioso); promover é review humano. Merge idempotente: re-submeter a mesma rule não duplica.

Devolve o **pack de leitura** de uma comunidade — código + evidência (#675). Quando usar: depois de escolher uma comunidade (via ``get_code_communities``/``get_structural_findings``) pra ler o código-fonte e extrair rules com o LLM do cliente (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: ``silex.business_logic.submit`` com as rules extraídas. Substrato da **arqueologia client-orchestrated** (ONBOARD-6): o server **não roda LLM**. Dado um escopo coeso (comunidade/package), esta tool resolve os membros (Postgres) e devolve o **código** dos chunks (do ``.silex/workspace.db`` free-tier, ONBOARD-2) + evidência estrutural (arquivo/classe/método/linhas/labels + arestas ``:REFERENCES`` intra-escopo), num formato enxuto pro **LLM do cliente** (claude-code) interpretar e extrair as rules — que voltam por ``silex.business_logic.submit``. Camada 1 (fato, fiel ao código). **Read-only** — não muta nada. Happy path free-tier: zero chave, zero GPU. **Orçamento por default (PACK-BUDGET-1 #1325):** comece SEM parâmetros — o pack já respeita um orçamento default (~40k chars) que cabe no teto de resultado do seu cliente MCP. Se houver mais código do que cabe, o retorno vem ``truncated: true`` com um ``next_cursor`` opaco e uma ``continuation_hint`` textual: chame de novo com ``cursor=<next_cursor>`` (mesmos parâmetros) pra pegar a próxima página. Pagine até o retorno vir sem ``next_cursor`` — a concatenação reconstrói o pack inteiro, byte a byte, sem perda. Corte é SEMPRE em fronteira de chunk (nunca código pela metade). Poder avançado: ``max_total_chars=0`` devolve tudo de uma vez (ilimitado); ``max_chunk_chars``/``max_chunks_per_member`` são knobs finos ortogonais ao orçamento. **Truncamento consciente de chunk (PACK-CHUNK-TRUNC-1 #1338):** quando ``max_chunk_chars`` corta o código de um chunk, o corte recua pra a última quebra de linha completa dentro do limite — nunca no meio de uma linha/método. O chunk truncado vem com ``truncated: true`` + ``chunk_handle`` opaco +…

Gera o **contrato de fato** (``fact_contract/v1``) de um escopo coeso. Quando usar: depois de ``silex.business_logic.submit`` (ou de rules heurísticas já materializadas), pra consolidar o escopo num contrato versionado (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: nenhum obrigatório — o ``fact_contract`` é o artefato de saída deste ramo do fluxo. Coleta as rules já extraídas (com provenance de símbolo) de uma comunidade/package materializada e as serializa num artefato versionado com ``status: proposed``. É agregação/serialização sobre o ``business_logic.json`` materializado — **não** nova extração. Camada 1 (fato, fiel ao código). Propor ledger candidato é MH-3; review/promoção ``proposed→active`` é MH-4 — fora desta tool.

Devolve o **agregado inteiro** (raiz + partes) em 1 chamada (#1141). Quando usar: pra responder "me explica o agregado X" — a pergunta nº1 da arqueologia. Prefira esta tool ao ``silex.community.code_pack`` quando você já sabe o NOME da entidade: o Leiden particiona por acoplamento, não por agregado, então o pack por comunidade quase nunca entrega o agregado inteiro (medido na cobaia eShop: a comunidade da raiz ``Order`` tem 7 membros, enquanto ``OrderItem``, ``Address``, ``Buyer`` e ``OrderStatus`` — o mesmo agregado — moram em 4 comunidades DIFERENTES). Esta tool ATRAVESSA comunidades. Próximo passo: ``silex.business_logic.submit`` com as rules extraídas. Camada 1 (fato, fiel ao código). **Read-only** — não muta nada. Roda no free-tier puro: só o ``.silex/workspace.db`` (sem Postgres/Neo4j). **Raiz determinística, nunca chute silencioso:** quando o nome casa com mais de uma classe (ex: o agregado ``Order`` de ``Ordering.Domain`` × o DTO homônimo do ``ClientApp``), a escolha usa sinais MEDIDOS do free-tier — rules ancoradas, nº de chunks, chars de código — e as candidatas rejeitadas voltam DECLARADAS em ``candidates`` com o motivo. Empate em todos os sinais → diagnostic ``entity_ambiguous`` com as candidatas, nunca um chute. **Toda âncora existe:** todo item traz arquivo:linha de um chunk real. Classe relacionada sem código (tipo de framework) é excluída e contada em ``metrics.unanchored_refs_excluded`` — nunca âncora inventada. **summary_first (default):** devolve só o MAPA do agregado (nomes + âncoras + comunidades), barato. Peça o código depois com ``summary_first=False``. O orçamento, o ``next_cursor`` e o ``chunk_handle`` são os MESMOS do ``silex.community.code_pack`` (PACK-BUDGET-1 #1325 / PACK-CHUNK-TRUNC-1 #1338): o payload INTEIRO respeita ``max_total_chars`` (default ~40k; ``0`` = ilimitado) e paginar até esgotar reconstrói o pack byte a byte.