cxpak

cxpak

Plano de contexto · Activo — en desarrollo; la superficie aún se mueve. Consulta el mapa de componentes para ver cómo encaja esto con el resto.

Gasta ciclos de CPU para que tú no gastes tokens.

cxpak indexa tu código usando tree-sitter en 44 lenguajes, construye un grafo de dependencias tipado y produce paquetes de contexto con presupuesto de tokens que le dan a los LLM un informe de situación en lugar de una linterna en una habitación oscura. Entiende la arquitectura de tu código, sus convenciones, su perfil de riesgo y su capa de datos — y luego empaqueta exactamente lo que el LLM necesita, nada más.

Cómo se ve

cxpak visual renderiza un panel de control autónomo de una sola página — tres modos, D3 incrustado, cero recursos externos, funciona sin conexión. Diecinueve paletas de colores integradas y una paleta de comandos Cmd+K sobre cada archivo, símbolo y vista. Cada número en la página se remonta a un cálculo real; haz clic en cualquier riesgo para ver su derivación exacta.

Resumen — un dial de salud tipo aguja y barras de genoma, riesgos principales clasificados, un feed de Señales probado y el código de barras de huella Repo-DNA.

Explorar — un lienzo espacial, lentes de Dependencias y Riesgo

Historial — la línea de tiempo de la arquitectura, revisada commit a commit

Instalación

brew tap Barnett-Studios/tap && brew install cxpak   # macOS/Linux
cargo install cxpak                                   # any platform, incl. Windows

En Windows, cargo install cxpak funciona, o descarga el cxpak-x86_64-pc-windows-msvc.zip precompilado desde la última versión.

Docker

Docker es una opción de despliegue de primera clase — útil en cualquier lugar donde quieras una instalación reproducible y aislada sin gestionar un toolchain de Rust: pipelines de CI, servidores en sandbox, máquinas Windows o entornos sin conexión a internet.

Imagen oficial (recomendada)

Las imágenes multi-arquitectura (amd64 / arm64) se publican en GitHub Container Registry en cada versión — sin compilación, sin toolchain de Rust, sin checkout del código fuente:

docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak overview .

Fija una etiqueta o un digest inmutable para despliegues reproducibles:

docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak:3.1.0 overview .
docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak@sha256:<digest> overview .

Las imágenes están firmadas con cosign (sin clave) y llevan SBOM + atestaciones de procedencia de compilación. Verifica antes de desplegar:

cosign verify ghcr.io/barnett-studios/cxpak:3.1.0 \
  --certificate-identity-regexp '^https://github.com/Barnett-Studios/cxpak/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Desde el código fuente

docker build -t cxpak .

Compila el conjunto completo de funcionalidades predeterminadas desde tu checkout local. La primera compilación es lenta (dependencias ML de candle); las compilaciones posteriores reutilizan una capa de dependencias en caché.

Autohospedado / sin conexión

Dockerfile.standalone obtiene el binario de versión precompilado, verifica su checksum SHA-256 y lo empaqueta en un runtime ubuntu:24.04 — sin checkout del código fuente ni toolchain de Rust. Todas las imágenes base y el binario descargado están fijados por digest para compilaciones reproducibles.

Los tres build-args son obligatorios — la compilación falla inmediatamente si se omite alguno, para que nunca puedas producir accidentalmente una imagen obsoleta o desajustada. Los checksums están disponibles en la página de versiones.

# SHA-256 values are per-release — copy the two for VERSION from the releases page.
docker build -f Dockerfile.standalone \
  --build-arg VERSION=3.1.0 \
  --build-arg SHA256_AMD64=<cxpak-x86_64-unknown-linux-gnu checksum> \
  --build-arg SHA256_ARM64=<cxpak-aarch64-unknown-linux-gnu checksum> \
  -t cxpak:3.1.0 .

Uso

El contenedor se ejecuta como un usuario no root; los pesos del modelo de incrustación (~30 MB, descargados en el primer uso) viven en /home/cxpak/.cxpak — monta un volumen con nombre allí para persistirlos entre ejecuciones.

macOS / Linux:

# One-shot command
docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak overview .

# HTTP server (--bind 0.0.0.0 required to reach the container from the host;
# --token is mandatory when binding to a non-loopback address)
docker run -d -p 3000:3000 \
  -v "$(pwd):/repo" \
  -v cxpak-models:/home/cxpak/.cxpak \
  ghcr.io/barnett-studios/cxpak serve --bind 0.0.0.0 --token mysecret .

# MCP — stdio only, one repo per instance (see note below)
docker run --rm -i -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak serve --mcp .

Windows (PowerShell):

# One-shot command
docker run --rm -v ${PWD}:/repo ghcr.io/barnett-studios/cxpak overview .

# HTTP server
docker run -d -p 3000:3000 `
  -v ${PWD}:/repo `
  -v cxpak-models:/home/cxpak/.cxpak `
  ghcr.io/barnett-studios/cxpak serve --bind 0.0.0.0 --token mysecret .

# Verify (use curl.exe — PowerShell's curl alias does not work here)
curl.exe http://localhost:3000/health

# MCP — stdio only, one repo per instance (see note below)
docker run --rm -i -v ${PWD}:/repo ghcr.io/barnett-studios/cxpak serve --mcp .

Reemplaza mysecret con cualquier secreto no vacío de tu elección. /health está abierto (GET) como sonda de liveness; cada otro endpoint requiere el token de portador cuando se establece uno (sin --token, en un bind de loopback, todas las rutas están abiertas):

curl http://localhost:3000/health                                        # no auth required
curl -X POST -H "Authorization: Bearer mysecret" http://localhost:3000/v1/conventions

HTTP vs MCP: Estos son dos transportes separados — no puedes usar el servidor HTTP como endpoint MCP.

Alcance de MCP: Cada instancia de MCP indexa exactamente un repositorio — la ruta pasada al inicio (. en los ejemplos anteriores, que se asigna al /repo montado). Para servir múltiples repositorios simultáneamente, ejecuta un contenedor por repositorio y registra cada uno en tu configuración de cliente MCP. El servidor HTTP tiene el mismo alcance de un solo repositorio.

Inicio rápido

# See your codebase the way an LLM should
cxpak overview .

# Trace a symbol through the dependency graph
cxpak trace "handle_request" .

# Generate an interactive dashboard
cxpak visual --visual-type dashboard .

# Get a guided reading order for onboarding
cxpak onboard .

Uso con herramientas de IA

Claude Code / Cursor (MCP)

Añade a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "cxpak": {
      "command": "cxpak",
      "args": ["serve", "--mcp", "."]
    }
  }
}

Tu herramienta de IA obtiene cinco herramientas parametrizadas por intención; cada una selecciona una capacidad mediante un argumento op obligatorio. cxpak_context (op: "context") es el punto de entrada principal — una llamada, contexto óptimo:

Herramienta de intención	Capacidades (vía op)
cxpak_context	context, retrieval, search, overview, stats, briefing, pack_context, context_for_task
cxpak_graph	graph (nodes/node/neighbors/path/subgraph), trace, blast_radius, call_graph, dead_code, api_surface, data_flow, cross_lang, predict
cxpak_data	data (esquema indexado / en vivo)
cxpak_review	review, diff, verify
cxpak_insight	health, risks, architecture, conventions, security_surface, drift, visual, onboard

Los nombres por herramienta de v2.x (cxpak_auto_context, cxpak_health, ...) siguen siendo invocables como alias obsoletos; tools/list no los anuncia, por lo que un cliente que construye su conjunto invocable desde la superficie anunciada no los encontrará. No hay una versión de eliminación establecida. Consulta docs/MIGRATION-3.0.md.

En repositorios grandes, cxpak serve --mcp responde al handshake MCP initialize inmediatamente y construye el índice en segundo plano — solucionando el timeout de inicio. Las llamadas a herramientas que llegan antes de que el índice esté listo reciben un estado de reintento elegante, y luego resultados byte-idénticos una vez construido.

Plugin de Claude Code

/plugin install cxpak

Se activa automáticamente en preguntas de arquitectura y revisiones de cambios. Comandos de barra: /cxpak:overview, /cxpak:trace, /cxpak:diff, /cxpak:clean.

Servidor HTTP

cxpak serve .                          # port 3000
cxpak serve --token my-secret .        # with Bearer auth on /v1/ endpoints
cxpak watch .                          # file watcher with hot index

LSP

cxpak lsp .                            # stdio, works with any LSP client

CodeLens, hover, diagnósticos, símbolos de espacio de trabajo, más 16 métodos personalizados cxpak/*. Soporta didOpen/didChange/didClose para reactividad en el editor.

Capacidades principales

Contexto automático

cxpak_context (op: "context") es el punto de entrada principal. Dale una tarea y un presupuesto de tokens; devuelve exactamente lo que el LLM necesita.

El pipeline: expansión de consulta con sinónimos específicos del dominio, puntuación de relevancia sobre 6 señales deterministas (palabra clave, símbolo, ruta, dominio, proximidad de importación, PageRank) fusionadas con Fusión de Rango Recíproco (RRF) — la clasificación predeterminada desde 3.0.0, medida +164% de recall sobre la suma ponderada anterior en un benchmark de 31 PR y determinista entre procesos — luego selección de semillas, filtrado de ruido, enriquecimiento de pruebas/esquema/radio de explosión, degradación progresiva (Completo > Recortado > Documentado > Firma > Stub) y anotaciones por archivo que explican por qué se incluyó cada archivo. Las incrustaciones son una séptima señal opcional (consulta Incrustaciones).

Cada respuesta comienza con una sección de ADN del Repositorio — un resumen de convenciones de ~1000 tokens para que el LLM sepa cómo escribe el código tu equipo antes de ver nada.

Inteligencia

Característica	Qué hace
Puntuación de Salud	Métrica compuesta entre convenciones, cobertura de pruebas, estabilidad de cambios, acoplamiento, ciclos, código muerto
Clasificación de Riesgo	Archivos clasificados por cambios x radio de explosión x brecha de pruebas — los que tienen más probabilidad de causar problemas
Arquitectura	Acoplamiento por módulo, cohesión, dependencias circulares, violaciones de límites, archivos dios
Radio de Explosión	Impacto de cambios: dependientes directos, dependientes transitivos, archivos de prueba, dependientes de esquema, cada uno con puntuaciones de riesgo
Predicción de Cambios	Señales estructurales + históricas (co-cambio de 180 días) + grafo de llamadas, confianza 0.3--0.9
Deriva de Arquitectura	Compara contra líneas base almacenadas; guarda automáticamente instantáneas para seguimiento de tendencias
Código Muerto	Símbolos con cero llamadores, clasificados por importancia (PageRank x visibilidad)
Grafo de Llamadas	Bordes de llamadas entre archivos con niveles de confianza Exacto/Aproximado
Superficie de Seguridad	Endpoints sin protección, secretos, inyección SQL, brechas de validación, puntuaciones de exposición en 12 frameworks
Flujo de Datos	Rastrea valores de origen a destino a través del grafo de llamadas; reporta cruces de límites de módulo/lenguaje/seguridad
Entre Lenguajes	Puentes HTTP, FFI, gRPC, GraphQL, esquema compartido y exec entre lenguajes

Inteligencia Visual

Seis vistas interactivas, HTML autónomo con D3.js. Sin paso de compilación, sin CDN.

cxpak visual --visual-type dashboard .
cxpak visual --visual-type architecture .
cxpak visual --visual-type risk .
cxpak visual --visual-type flow --symbol handle_request .
cxpak visual --visual-type timeline .
cxpak visual --visual-type diff --files "src/api.rs,src/db.rs" .

Formatos de exportación: HTML, Mermaid, SVG, PNG, C4 DSL, JSON.

Motor de diseño: método de Sugiyama con condensación SCC, minimización de cruces por baricentro, asignación de coordenadas Brandes-Kopf y agrupación cognitiva 7+/-2.

Convenciones

Extrae un perfil de convenciones cuantificado de lo que tu equipo realmente hace: nombres, imports, manejo de errores, dependencias, pruebas, visibilidad, longitud de funciones, salud de git. Cada patrón tiene conteos, porcentajes y etiquetas de fuerza (Convención >= 90%, Tendencia >= 70%, Mixto).

cxpak_review (op: "verify") verifica cambios de código contra convenciones observadas — solo marca violaciones en líneas cambiadas. cxpak conventions export/diff habilita detección de deriva en CI con checksums SHA256.

Incorporación

cxpak onboard .

Genera una guía de lectura ordenada por dependencias: archivos ordenados topológicamente, agrupados en fases por módulo, ordenados por PageRank. Cada archivo lista los símbolos clave en los que enfocarse y un tiempo de lectura estimado.

Soporte de lenguajes (44)

Extracción completa (funciones, clases, métodos, imports, exports): Rust, TypeScript, JavaScript, Python, Java, Go, C, C++, Ruby, C#, Swift, Kotlin, Bash, PHP, Dart, Scala, Lua, Luau, Elixir, Zig, Haskell, Groovy, Objective-C, R, Julia, OCaml, MATLAB, Clojure

Extracción estructural (selectores, claves, bloques): CSS, SCSS, Markdown, JSON, YAML, TOML, Dockerfile, HCL/Terraform, Protobuf, Svelte, Makefile, HTML, GraphQL, XML

DSLs de bases de datos: SQL, Prisma

Conciencia de la capa de datos

cxpak entiende tu capa de datos y la usa para construir un grafo de dependencias más rico:

• Detección de esquema -- DDL de SQL, Prisma, Django, SQLAlchemy, TypeORM, ActiveRecord
• Secuencias de migración -- Rails, Alembic, Flyway, Django, Knex, Prisma, Drizzle
• Vinculación de SQL incrustado -- SQL en línea en código de aplicación crea bordes hacia definiciones de tablas
• Linaje a nivel de columna -- impacto rastreado a granularidad de columna: "alterar users.email" se resuelve a las consultas específicas, modelos ORM, endpoints y pruebas que referencian esa columna, y el radio de explosión de una columna diferente excluye los archivos solo de email
• Introspección de base de datos en vivo -- conéctate a un Postgres o MySQL en ejecución e indexa el esquema en vivo, luego calcula la deriva contra el esquema que el código declara. Controladores rustls puramente en Rust (sin OpenSSL), solo lectura, y el DSN nunca se registra ni persiste. Desactivado por defecto; habilitado con la característica de compilación data-introspect
• Tipos de bordes tipados -- Import, ForeignKey, ViewReference, EmbeddedSql, OrmModel, MigrationSequence, ColumnReference, CrossLanguage y más. Cada borde lleva un marcador de confianza; los bordes heurísticos (inferidos) están etiquetados para que una suposición de regex nunca se confunda con una dependencia estructuralmente probada

Consulta y exportación de grafos

Consulta el grafo de dependencias tipado directamente: cinco primitivas (nodes, node, neighbors, path, subgraph), idénticas en MCP, HTTP, LSP y CLI. Las aristas llevan un edge_type tipado y un marcador de confianza; las aristas inferidas (heurísticas) se muestran como tales. nodes enumera cada id válido sin argumentos: la forma de descubrir los ids (son rutas de archivo relativas al repositorio) antes de llamar a los demás; subgraph informa de cualquier semilla que no sea un nodo real en unknown_seeds en lugar de devolverla como si lo fuera.

cxpak graph nodes .
cxpak graph neighbors --id src/index/graph.rs .
cxpak graph path --from src/main.rs --to src/output/mod.rs .
cxpak graph subgraph --seeds src/scanner/mod.rs,src/parser/mod.rs --depth 2 .

Exporta el grafo a Cypher (Neo4j) o GraphML (Gephi, yEd, NetworkX) con las mismas aristas tipadas honestas y la confianza por arista:

cxpak visual --format cypher .
cxpak visual --format graphml .

Incrustaciones (embeddings)

La similitud semántica es una opcional 7.ª señal de puntuación, activada explícitamente mediante .cxpak.json. Sin esa configuración se usan las 6 señales deterministas por defecto y no se descarga ningún modelo. Cuando está configurado, cxpak usa inferencia local con all-MiniLM-L6-v2 (~30 MB, descargado en el primer uso) o un proveedor remoto (OpenAI, Voyage AI o Cohere con tu propia clave). En cxpak serve --mcp el índice de incrustaciones se construye en segundo plano, fuera de la ruta de arranque, por lo que nunca retrasa el protocolo de enlace de MCP; si falla, cxpak vuelve a las 6 señales deterministas.

Configuración local mínima:

{ "embeddings": { "provider": "local" } }

Cargador de plugins WASM: un esqueleto, no un SDK funcional

Hoy no puedes ampliar cxpak con un plugin WASM. PluginLoader::load() verifica la suma de comprobación del módulo, lo compila, lo instancia y luego devuelve guest function binding not yet implemented. El puente WIT que haría invocable una función invitada no existe, por lo que ningún código de plugin se ha ejecutado jamás.

La funcionalidad plugins queda por tanto excluida de default: un cargo install cxpak estándar no lo compila, y los comandos de gestión de plugins están detrás de la misma puerta. Lo que está desarrollado es la ruta de carga: un manifiesto con verificación SHA-256 antes de la compilación, un límite de módulo de 10 MiB, un limitador de memoria de 64 MiB y un plazo de época de 10 s. No trates nada de esto como un límite de seguridad hasta que el puente llegue y se cierren las brechas en SECURITY.md — #42.

Soporte de espacios de trabajo

Para monorepos: --workspace packages/api limita el escaneo a un subdirectorio manteniendo el repositorio completo como raíz de git.

Exclusión de archivos

El escaneo respeta .gitignore y, además, un .cxpakignore opcional en la raíz del repositorio. Acepta la misma sintaxis que .gitignore:

# Generated code
generated/
*.generated.ts

# Large test fixtures
tests/fixtures/large/

Úsalo para archivos que pertenecen al repositorio pero no al paquete de contexto — salida generada, árboles de terceros, fixtures — o para omitir un único archivo que una gramática analiza mal. .cxpakignore.example en este repositorio es un punto de partida.

Caché

Los resultados del análisis se guardan en caché en .cxpak/cache/ con clave basada en la fecha de modificación y el tamaño del archivo. La caché se invalida automáticamente cuando cambian las versiones de las gramáticas de tree-sitter. Escrituras atómicas con bloqueo de asesoramiento para seguridad en procesos concurrentes. cxpak clean . para restablecer.

Cliente Rust (funcionalidad no predeterminada client)

Los llamadores Rust pueden comunicarse con un servidor MCP de cxpak a través del cliente oficial en lugar de improvisar una sesión rmcp. Está desactivado por defecto, por lo que cargo install cxpak sigue compilando un indexador y no extrae rmcp:

[dependencies]
cxpak = { version = "3.1", features = ["client"] }

Si quieres el cliente sin las 44 gramáticas incluidas, default-features = false, features = ["client", "daemon"] builds the library — daemon is currently the floor, not client solo.

CxpakClient es un método, y su tipo de retorno es el contrato:

use cxpak::client::{CxpakClient, RmcpCxpakClient};
use serde_json::json;

let client = RmcpCxpakClient::new(std::env::current_dir()?);
match client.call("cxpak_context", json!({"op": "overview"})).await {
    Some(bundle) => use_it(bundle),
    // NOT "the server looked and found nothing" — the tool was unavailable, errored,
    // or degraded. Map it to a skipped observation, never to a verdict.
    None => skip(),
}

RmcpCxpakClient es perezoso: no se genera ningún proceso hijo hasta la primera llamada, los procesos se reintentan con retroceso tras fallos repetidos, y el stderr del hijo se anula para que un banner del servidor nunca pueda contaminar a un llamador que no debe escribir en stderr (un hook, por ejemplo).

Para tus propias pruebas, RecordedCxpakClient reproduce un mapa name → response sin E/S, y from_dir carga un directorio de grabaciones <tool>.json confirmadas. Un directorio ausente es un error, no un cliente vacío: un conjunto de fixtures mal ruteado que informa de una ejecución limpia sobre nada es el fallo que este constructor se niega a tener.

use cxpak::client::RecordedCxpakClient;
let client = RecordedCxpakClient::from_dir(std::path::Path::new("recordings/cxpak"))?;

La funcionalidad añade rmcp, y solo rmcp, a lo que se compila (async-trait ya está en el árbol predeterminado de forma transitiva). CI verifica ambas direcciones: que el cliente compila y que sus pruebas se ejecutan, y que rmcp permanece fuera del árbol de dependencias predeterminado.

API estable

v2.0.0 establece semver para la API MCP. Los nombres de herramientas, parámetros y estructuras de respuesta son estables en 2.x.

3.0.0 consolida las 26 herramientas MCP en 5 herramientas parametrizadas por intención (cxpak_context, cxpak_graph, cxpak_data, cxpak_review, cxpak_insight), cada una seleccionando una capacidad mediante un argumento op obligatorio. Este es el único cambio disruptivo en 3.0.0 y afecta solo a los clientes MCP: la CLI, la API /v1/* HTTP y los métodos cxpak/* LSP no cambian. Los 26 nombres antiguos de herramientas siguen siendo invocables como alias obsoletos y no descubribles durante una versión. Consulta docs/MIGRATION-3.0.md.

Decisiones de arquitectura

Cada decisión arquitectónicamente significativa se registra como ADR en docs/adrs/: qué se eligió, las opciones consideradas y las condiciones para revisarla. Los registros abarcan análisis, el grafo de dependencias tipado, puntuación de relevancia, presupuesto de tokens, las superficies MCP/HTTP/LSP y distribución. Los registros 0001-0162 se reconstruyeron en v0.1.0 -> v2.2.1; del 0163 en adelante se escriben en el momento de la decisión, ahora hasta 0199 (v3.1.0). Empieza con el índice.

Licencia

Licenciado bajo MIT o Apache-2.0, a tu elección. Salvo que indiques explícitamente lo contrario, cualquier contribución que envíes intencionadamente para su inclusión en el trabajo se licenciará de forma dual como se indica arriba, sin términos adicionales.

---

Construido por Barnett Studios: creando productos, equipos y sistemas que perduran.