Smart CLI

Hub de producto de @evolith/smart-cli — el punto de entrada por línea de comandos al ecosistema Evolith: gobernanza, validación de estándares, andamiaje de arquitectura, gestión del ciclo de vida SDLC e integración con agentes de IA (MCP).


Estado	Activo
Paquete	`@evolith/smart-cli`
Versión	`1.1.4`
Binario	`smart-cli`
Fuente de verdad	`sdk/cli/README.md` (autoritativo, 1200+ líneas)
Inventario de superficie	`product-inventory.md` (generado — no editar a mano)

Esta página es un hub: te orienta y te dirige a la documentación profunda autoritativa. Para las opciones exhaustivas de cada comando, remítete siempre al README de código y al Inventario de Superficie de Producto generado.

Qué hace

Gobernanza — gestión de ADRs, seguimiento de estándares, instalación de agentes BMAD.
Validación — cumplimiento del repositorio contra rulesets, topologías, ADRs y gates SDLC de Evolith (motor componible, GT-312).
Arquitectura — andamiaje y detección de deriva a lo largo del eje progresivo de madurez.
Ciclo de vida SDLC — gates de fase, transiciones, artefactos de handoff y métricas DORA.
Integración con IA — un servidor MCP listo para producción (stdio + HTTP) para Cursor, Claude Desktop y agentes propios.

Instalación

npm install -g @evolith/smart-cli
# o: pnpm add -g @evolith/smart-cli
# o: yarn global add @evolith/smart-cli

O descarga un binario desde GitHub Releases y añádelo a tu PATH.

smart-cli --version
# smart-cli version 1.1.4

Inicio rápido

# 1. Genera un proyecto de demostración para explorar la CLI
smart-cli fixtures --type demo

# 2. Inicializa un repositorio real (crea evolith.yaml)
smart-cli init

# 3. Genera la documentación base
smart-cli docs

# 4. Valida el cumplimiento
smart-cli validate

# 5. Conecta un agente de IA
smart-cli mcp serve

Referencia de comandos

La CLI expone 20 grupos de comandos (el inventario generado cuenta subcomandos por separado, de ahí una cifra mayor). Una línea concisa por cada uno — para las opciones y ejemplos completos, sigue el enlace al README de código.

Comando	Propósito
`init`	Inicializa un repositorio satélite (crea `evolith.yaml` y la estructura del proyecto).
`docs`	Genera la documentación base (`README.md`, `AGENTS.md`, `MASTER_INDEX.md`, `evolith.yaml`).
`validate`	Valida el cumplimiento del repositorio contra rulesets, topologías, ADRs y fases SDLC.
`adr`	Gestiona Architecture Decision Records (create, list, get, update, matrix).
`standards`	Gestiona estándares de gobernanza (init, list, get, validate, export).
`agents`	Instala, lista y elimina agentes BMAD de Evolith.
`architecture`	Inspecciona y valida la arquitectura contra la topología declarada.
`drift`	Detecta la deriva de arquitectura respecto a la topología declarada; registra historial y tendencias.
`gate`	Evalúa los gates de fase SDLC y emite artefactos `GateEvidence` (ADR-0073).
`phase`	Propone una transición entre fases SDLC (emite un artefacto de propuesta).
`sdlc`	Orquesta artefactos y ciclo de vida SDLC (`handoff`, `generate`, `gate-status`).
`profile`	Gestiona perfiles de CLI con nombre (valores por defecto por entorno).
`fixtures`	Genera archivos de fixtures reproducibles para demos, pruebas y onboarding.
`api`	Explora e inspecciona la superficie de la API de Evolith (herramientas MCP, recursos, esquemas, comandos).
`mcp`	Ejecuta el servidor MCP para integración con agentes de IA (stdio o HTTP).
`alias`	Gestiona alias abreviados para comandos de la CLI.
`history`	Visualiza y gestiona el historial de ejecución de comandos.
`completion`	Genera e instala scripts de autocompletado de shell (bash, zsh, fish).
`update`	Comprueba y aplica actualizaciones de la CLI.
`upgrade`	Actualiza un repositorio satélite a la siguiente topología del eje progresivo o versión de gobernanza.

Modos de validación (motor componible — GT-312)

La validación es componible, no rígida — puedes entrar desde cualquier combinación de inputs y el motor resuelve el alcance óptimo.

Modo	Ejemplo	Valida
SDLC	`smart-cli validate --phase discovery`	Fase → gate → artefactos → esquemas → rulesets → ADRs → criterios de bloqueo
Arquitectura	`smart-cli validate --topology modular-monolith`	Reglas de topología, límites hexagonales, aislamiento de dominio, multi-tenencia
Ruleset	`smart-cli validate --ruleset evidence`	Un ruleset específico (motor native u OPA)
ADR	`smart-cli validate --adr adr-0002`	Reglas arquitectónicas específicas de un ADR
Ad-hoc	`smart-cli validate --file src/domain/user.ts`	Un único archivo o componente
Componible	`smart-cli validate --topology microservices --ruleset evidence`	Varios puntos de entrada combinados

Claves de fase SDLC (los valores de --phase aceptados por la CLI y la API de @evolith/sdk-client): discovery, design, construction, qa, release. Mapean a las fases de gobernanza f1–f5 — Conception & Discovery, Design & Architecture, Construction, Validation & QA, Delivery & Operations — ver Fases y gates más abajo. Las claves heredadas f1–f5 están obsoletas como valores de --phase; usa las claves canónicas anteriores.

# Comprobación básica de cumplimiento
smart-cli validate

# Salida JSON para CI (envelope ADR-0073)
smart-cli validate --format json --output report.json

# Evaluación de fase SDLC (pipeline GT-281)
smart-cli validate --phase discovery

# Motor OPA contra un ruleset específico
smart-cli validate --engine opa --ruleset acl

Topologías soportadas

Cualquier comando que acepte --topology referencia los 8 ids canónicos de topología por su dimensión:

Topología (id)	Dimensión
`modular-monolith`	eje-progresivo
`distributed-modules`	eje-progresivo
`microservices`	eje-progresivo
`serverless`	ejecución
`edge-computing`	ejecución
`event-driven`	integración
`data-mesh`	datos
`agentic-ai`	ia

El eje progresivo (modular-monolith → distributed-modules → microservices) es una progresión lineal de madurez. Las demás dimensiones (ejecución, integración, datos, ia) son complementarias y se eligen según las necesidades del proyecto. Los flags heredados F1/F2/F3 mapean al eje progresivo pero están obsoletos — usa los ids canónicos.

Fases y gates SDLC

F1–F5 son niveles de madurez en el eje progresivo de arquitectura, no fases SDLC. El ciclo de vida SDLC es un modelo independiente:

Fase de gobernanza	Nombre corto	Clave CLI `--phase`	Gate
Conception & Discovery	Discovery	`discovery`	Business Sign-Off
Design & Architecture	Architecture	`design`	Design Baseline Approved
Construction	Build	`construction`	Successful Build
Validation & QA	Validation	`qa`	RC Stamped
Delivery & Operations	Delivery	`release`	Production Live

La fase final del SDLC es Delivery & Operations. Evalúa gates y emite evidencia con smart-cli gate evaluate --phase <clave>; propón transiciones con smart-cli phase advance.

Servidor MCP (integración con agentes de IA)

El servidor MCP se distribuye dentro de @evolith/smart-cli — no hay instalación aparte. Expone la superficie completa de Evolith a los agentes de IA.

Superficie	Cantidad
Herramientas	27
Recursos	9
Prompts	8
Transportes	`stdio` (JSON-RPC 2.0) · Streamable HTTP (clave API, fail-closed)

El conjunto exacto de herramientas/recursos/prompts se enumera en el Inventario de Superficie de Producto generado y se puede explorar en vivo con smart-cli api --list --category tools. Trátalos como la autoridad en lugar de cualquier lista mantenida a mano.

# Transporte stdio (por defecto — Cursor, Claude Desktop)
smart-cli mcp serve

# Transporte HTTP con autenticación por clave API (remoto / contenedorizado)
smart-cli mcp serve --transport http --port 3000 --api-key <secret>

Cursor (~/.cursor/mcp.json) / Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "evolith": {
      "command": "smart-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Configuración

Evolith usa evolith.yaml en .evolith/ o en la raíz del repositorio:

coreRef:
  version: "1.0.0"
  path: "../../evolith"

governance:
  version: "1.0"
  adrRegistry:
    - id: "ADR-0001"
      status: "accepted"

product:
  name: "my-project"
  type: "library"
  runtime: "typescript"
  topology: "modular-monolith"

Los valores por defecto opcionales que consume validate (topología, fase, rulesets, engine) también viven en evolith.yaml — smart-cli validate sin flags los lee. Usa una clave de fase canónica (discovery…release) y un id de topología canónico.

Dónde encaja en Evolith

Smart CLI forma parte de la suite Evolith, construida sobre Evolith Core (packages/core, core-domain, infra-providers, sdk-client, mcp-tools). Productos hermanos: Evolith Tracker, Core API (apps/core-api), Evolith MCP Services y el modelo de referencia UMS Reference.

Documentación

README de código — autoritativo, referencia completa por comando y ejemplos.
Inventario de Superficie de Producto — recuentos generados de herramientas/recursos/prompts/comandos.
Guía de demostración — recorrido de extremo a extremo.
Integración MCP — detalles del protocolo MCP.
Protocolo de Handoff — especificación del artefacto de handoff SDLC.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Smart CLI

Qué hace

Instalación

Inicio rápido

Referencia de comandos

Modos de validación (motor componible — GT-312)

Topologías soportadas

Fases y gates SDLC

Servidor MCP (integración con agentes de IA)

Configuración

Dónde encaja en Evolith

Documentación

Soporte

Uh oh!

FilesExpand file tree

README.es.md

Latest commit

History

README.es.md

File metadata and controls

Smart CLI

Qué hace

Instalación

Inicio rápido

Referencia de comandos

Modos de validación (motor componible — GT-312)

Topologías soportadas

Fases y gates SDLC

Servidor MCP (integración con agentes de IA)

Configuración

Dónde encaja en Evolith

Documentación

Soporte