tramalia-cli 0.9.1__py3-none-any.whl

tramalia/__init__.py

@@ -0,0 +1,11 @@
+"""Tramalia: capa fina de orquestación para desarrollo con múltiples agentes IA.
+
+Principio de diseño: Tramalia no implementa capacidades, las orquesta.
+Diagnostica (doctor), delega la ejecución a herramientas externas (mise, copier,
+serena, semgrep, ...) y solo construye lo que nadie más hace bien
+(detector, evidence pack y handoff).
+"""
+
+__version__ = "0.9.1"
+__author__ = "Michael Jim Scott Bravo"
+__license__ = "Apache-2.0"

tramalia/__main__.py

@@ -0,0 +1,96 @@
+"""Punto de entrada de la CLI. Usa argparse (stdlib) para no exigir dependencias;
+Rich/Questionary se activan solos si están instalados (extra `pretty`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tramalia import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="tramalia",
+        description="Capa fina que orquesta herramientas externas para desarrollo con agentes IA.",
+    )
+    p.add_argument("--version", action="version", version=f"tramalia {__version__}")
+    p.add_argument("--plain", action="store_true", help="salida sin colores (terminal básica)")
+    sub = p.add_subparsers(dest="command")
+
+    sub.add_parser("menu", help="menú interactivo")
+    d = sub.add_parser("doctor", help="diagnostica las herramientas requeridas")
+    d.add_argument("--fix", action="store_true", help="intenta instalar lo que falte vía mise")
+    sub.add_parser("detect", help="detecta el stack del proyecto")
+    ini = sub.add_parser("init", help="inicializa la estructura (copier)")
+    ini.add_argument("--with-headroom", action="store_true",
+                     help="agrega Headroom (compresión) al .mcp.json (opt-in explícito)")
+    ini.add_argument("--with-ponytail", action="store_true",
+                     help="agrega el MCP de Ponytail al .mcp.json (requiere `tramalia skills` + Node)")
+    sub.add_parser("gates", help="ejecuta quality gates (mise run gates)")
+    sub.add_parser("context", help="genera contexto / token-saver (repomix + serena)")
+    ev = sub.add_parser("evidence", help="genera el evidence pack (ej: tramalia evidence TASK-001)")
+    ev.add_argument("task_pos", nargs="?", metavar="TAREA", default=None,
+                    help="ID de la tarea; si se omite, se usa .tramalia/current-task.md")
+    ev.add_argument("--task", default=None, help="ID de la tarea (alternativa al posicional)")
+    ev.add_argument("--engram", action="store_true",
+                    help="exporta a Engram (memoria persistente N2, opt-in)")
+    ho = sub.add_parser("handoff", help="crea un handoff multiagente (ej: tramalia handoff TASK-001)")
+    ho.add_argument("task_pos", nargs="?", metavar="TAREA", default=None,
+                    help="ID de la tarea; si se omite, se usa .tramalia/current-task.md")
+    ho.add_argument("--task", default=None, help="ID de la tarea (alternativa al posicional)")
+    ho.add_argument("--agent", default=None, help="agente ejecutor (def: config agents.primary)")
+    ho.add_argument("--reviewer", default=None, help="agente revisor (def: config agents.reviewer)")
+    ho.add_argument("--engram", action="store_true",
+                    help="exporta a Engram (memoria persistente N2, opt-in)")
+    cl = sub.add_parser("close",
+                        help="ritual de cierre: gates → evidence → handoff (ej: tramalia close TASK-001)")
+    cl.add_argument("task_pos", nargs="?", metavar="TAREA", default=None,
+                    help="ID de la tarea; si se omite, se usa .tramalia/current-task.md")
+    cl.add_argument("--task", default=None, help="ID de la tarea (alternativa al posicional)")
+    cl.add_argument("--agent", default=None, help="agente ejecutor (def: config agents.primary)")
+    cl.add_argument("--reviewer", default=None, help="agente revisor (def: config agents.reviewer)")
+    cl.add_argument("--allow-fail", action="store_true",
+                    help="cierra aunque fallen gates (requiere excepción documentada)")
+    cl.add_argument("--model", default=None,
+                    help="modelo usado por el agente ejecutor (queda en metadata.json)")
+    cl.add_argument("--engram", action="store_true", help="exporta el cierre a Engram (N2)")
+    sub.add_parser("log", help="pista de auditoría: cierres registrados (evidence packs)")
+    sy = sub.add_parser("sync", help="propaga reglas y subagentes a otros agentes (rulesync)")
+    sy.add_argument("--to", default=None,
+                    help="targets separados por coma (def: copilot,cursor,cline)")
+    sy.add_argument("--features", default=None,
+                    help="features de rulesync a propagar (def: rules,subagents)")
+    sk = sub.add_parser("skills", help="administra skills declaradas (.tramalia/skills.toml)")
+    sk.add_argument("action", nargs="?", choices=["sync", "list"], default="sync")
+    sub.add_parser("update", help="actualiza todo (mise + copier + skills)")
+    sub.add_parser("mcp", help="levanta el Tramalia MCP (fachada nivel 1, stdio)")
+    sub.add_parser("ui", help="abre el dashboard TUI (requiere extra [tui])")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    # En Windows la consola puede no ser UTF-8; lo forzamos para acentos y símbolos.
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    raw = list(argv if argv is not None else sys.argv[1:])
+    # --plain se acepta en cualquier posición; se extrae antes de parsear
+    plain = "--plain" in raw
+    raw = [a for a in raw if a != "--plain"]
+    args = build_parser().parse_args(raw)
+
+    from tramalia.cli import render
+    if plain:
+        render.set_plain(True)
+
+    from tramalia.cli import commands
+    return commands.dispatch(args.command or "menu", args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tramalia/cli/commands.py

@@ -0,0 +1,363 @@
+"""Implementación de cada comando. La mayoría hace *shell-out* transparente a la
+herramienta real (regla de diseño: el façade muestra el comando, pasa la salida
+tal cual y nunca esconde errores). doctor/detect son lógica propia.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from tramalia.cli import menu, render
+from tramalia.core import doctor as doctor_core
+from tramalia.core import proc
+from tramalia.core.detect import detect_stack, enabled_features
+
+
+def _is_initialized(root: Path) -> bool:
+    return (root / "AGENTS.md").exists() or (root / ".tramalia").exists()
+
+
+def _run(cmd: list[str]) -> int:
+    """Ejecuta un comando externo mostrando exactamente su salida."""
+    render.info(f"→ {' '.join(cmd)}")
+    try:
+        return proc.run(cmd).returncode
+    except FileNotFoundError:
+        render.err(f"no se encontró '{cmd[0]}'. Corre `tramalia doctor` para instalarlo.")
+        return 127
+
+
+# --------------------------------------------------------------------------- #
+
+def cmd_doctor(args) -> int:
+    report = doctor_core.diagnose(Path.cwd())
+    code = render.doctor(report)
+    if getattr(args, "fix", False) and report.missing_blocking:
+        if doctor_core.fix(report):
+            render.info("`mise install` ejecutado; re-evaluando…")
+            return render.doctor(doctor_core.diagnose(Path.cwd()))
+        render.warn("no se pudo auto-instalar (instala primero mise — ver enlace arriba).")
+    return code
+
+
+def cmd_detect(args) -> int:
+    root = Path.cwd()
+    stack = detect_stack(root)
+    feats = enabled_features(stack)
+    render.header(root.name, stack, _is_initialized(root))
+    render.info(f"gates aplicables: {', '.join(feats)}")
+    return 0
+
+
+def cmd_init(args) -> int:
+    from tramalia.core import scaffold
+    root = Path.cwd()
+    stack = detect_stack(root)
+    answers = {
+        "project_name": root.name,
+        "stacks": stack,
+        "features": enabled_features(stack),
+        "primary_agent": "codex",
+        "reviewer_agent": "claude",
+        "with_headroom": getattr(args, "with_headroom", False),
+        "with_ponytail": getattr(args, "with_ponytail", False),
+    }
+    render.header(root.name, stack, _is_initialized(root))
+    results = scaffold.scaffold(root, answers)
+    for rel, state in results:
+        (render.ok if state == "creado" else render.info)(f"{state:>6}  {rel}")
+    creados = sum(1 for _, s in results if s == "creado")
+    render.ok(f"init listo: {creados} creados, {len(results) - creados} ya existían.")
+    render.info("revisa AGENTS.md y mise.toml; instala lo que falte con `tramalia doctor`.")
+    return 0
+
+
+def cmd_gates(args) -> int:
+    if shutil.which("mise") is None:
+        render.err("falta 'mise'. Corre `tramalia doctor` para los pasos de instalación.")
+        return 127
+    return _run(["mise", "run", "gates"])
+
+
+def cmd_context(args) -> int:
+    from tramalia.core import context
+    results = context.build_context(Path.cwd())
+    for rel in results:
+        render.ok(f"generado  .tramalia/context/{rel}")
+    if shutil.which("repomix") is None:
+        render.info("repomix ausente: project-map se generó con el árbol stdlib.")
+        render.info("para snapshot completo: `mise use npm:repomix`.")
+    return 0
+
+
+def _engram_save(title: str, body: str) -> None:
+    """Export opt-in a Engram (memoria persistente N2). Nunca automático."""
+    if shutil.which("engram") is None:
+        render.warn("engram no está instalado; se omite el export a memoria persistente.")
+        return
+    if _run(["engram", "save", title, body]) == 0:
+        render.ok("exportado a Engram (memoria persistente N2).")
+
+
+def _interactive_ask_task():
+    """Prompt de tarea solo si hay terminal interactiva (los scripts no se cuelgan)."""
+    import sys
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        return None
+    return lambda: menu.ask_text("ID de la tarea (ver specs/tasks.md)", "TASK-001")
+
+
+def _resolver(args):
+    """Aplica la cadena de defaults: posicional > --task > current-task > prompt."""
+    from tramalia.core import project
+    return project.resolve_close_args(
+        Path.cwd(),
+        getattr(args, "task_pos", None),
+        getattr(args, "task", None),
+        getattr(args, "agent", None),
+        getattr(args, "reviewer", None),
+        ask=_interactive_ask_task(),
+    )
+
+
+def cmd_evidence(args) -> int:
+    from tramalia.core import evidence
+    task, _, _ = _resolver(args)
+    target = evidence.build_evidence(Path.cwd(), task)
+    render.ok(f"evidence pack creado: {target.relative_to(Path.cwd())}")
+    render.info("completa summary.md, risks.md y next-steps.md antes de cerrar.")
+    if getattr(args, "engram", False):
+        _engram_save(f"evidence {task}", f"Evidence pack de {task} en {target}.")
+    return 0
+
+
+def cmd_handoff(args) -> int:
+    from tramalia.core import handoff
+    task, agent, reviewer = _resolver(args)
+    path = handoff.new_handoff(Path.cwd(), task, agent, reviewer)
+    render.ok(f"handoff agregado a {path.relative_to(Path.cwd())}")
+    if getattr(args, "engram", False):
+        _engram_save(f"handoff {task}",
+                     f"Handoff de {task}; ejecutor {agent or '?'}, revisor {reviewer or '?'}.")
+    return 0
+
+
+def cmd_close(args) -> int:
+    from tramalia.core import governance
+    task, agent, reviewer = _resolver(args)
+    res = governance.close(
+        Path.cwd(), task, agent, reviewer,
+        allow_fail=getattr(args, "allow_fail", False),
+        model=getattr(args, "model", None) or "",
+    )
+    if not res.gates_ran:
+        render.warn("gates no ejecutados (mise ausente); registrado como excepción en el pack.")
+    else:
+        for name, code, _ in res.gates:
+            (render.ok if code == 0 else render.err)(
+                f"gate {name}: {'ok' if code == 0 else 'FALLA'}")
+    render.ok(f"evidence: {res.evidence_dir.relative_to(Path.cwd())}  (estado: {res.status})")
+    render.ok(f"handoff: {res.handoff_path.relative_to(Path.cwd())}")
+    render.info(f"metadata: {(res.evidence_dir / 'metadata.json').relative_to(Path.cwd())}")
+    if getattr(args, "engram", False):
+        _engram_save(f"close {task}",
+                     f"Cierre de {task}; estado {res.status}; fallidos: {', '.join(res.failed) or 'ninguno'}.")
+    if res.blocked:
+        render.err(f"cierre BLOQUEADO por gates fallidos: {', '.join(res.failed)}.")
+        render.info("usa --allow-fail solo con una excepción documentada en risks.md.")
+        return 1
+    render.ok(f"tarea {task} cerrada con evidencia verificable.")
+    return 0
+
+
+_LOG_MARKS = {
+    "passed": "✓ passed",
+    "passed_with_exceptions": "⚠ con excepciones (forzado)",
+    "blocked": "✗ bloqueado",
+    "no_gates": "○ sin gates",
+    None: "○ —",
+}
+
+
+def cmd_log(args) -> int:
+    from tramalia.core import governance
+    entries = governance.read_log(Path.cwd())
+    if not entries:
+        render.info("sin cierres registrados todavía. Usa `tramalia close`.")
+        return 0
+    render.info(f"pista de auditoría — {len(entries)} cierres (más reciente primero):")
+    for e in entries:
+        mark = _LOG_MARKS.get(e.get("status"), "○ —")
+        extra = f"  ·  {e['agent']}" if e.get("agent") else ""
+        if e.get("model"):
+            extra += f" ({e['model']})"
+        render.ok(f"{e['id']}  ·  {mark}{extra}")
+    return 0
+
+
+def cmd_sync(args) -> int:
+    if shutil.which("rulesync") is None:
+        render.err("falta 'rulesync'. Instálalo con: mise use npm:rulesync")
+        return 127
+    if not (Path.cwd() / "AGENTS.md").exists():
+        render.err("no hay AGENTS.md. Ejecuta `tramalia init` primero.")
+        return 1
+    # CLAUDE.md/Codex no se incluyen: ya leen AGENTS.md nativamente.
+    # Targets válidos en rulesync v9: copilot, cursor, cline, antigravity-cli, zed, junie, warp, …
+    targets = getattr(args, "to", None) or "copilot,cursor,cline"
+    wanted = {f.strip() for f in
+              (getattr(args, "features", None) or "rules,subagents").split(",") if f.strip()}
+    code = 0
+    if "rules" in wanted:
+        render.info(f"reglas: AGENTS.md → {targets} (rulesync)")
+        code |= _run(["rulesync", "convert", "--from", "agentsmd",
+                      "--to", targets, "--features", "rules"])
+    if "subagents" in wanted:
+        if (Path.cwd() / ".claude" / "agents").exists():
+            render.info(f"subagentes: .claude/agents → {targets} (rulesync)")
+            # best-effort: no todos los targets soportan subagentes; rulesync lo reporta.
+            code |= _run(["rulesync", "convert", "--from", "claudecode",
+                          "--to", targets, "--features", "subagents"])
+        else:
+            render.info("sin .claude/agents; omitiendo fan-out de subagentes.")
+    return code
+
+
+def cmd_skills(args) -> int:
+    from tramalia.core import skills
+    root = Path.cwd()
+    action = getattr(args, "action", None) or "sync"
+
+    if action == "list":
+        items = skills.read_skills(root)
+        if not items:
+            render.info("no hay skills declaradas en .tramalia/skills.toml")
+        for s in items:
+            render.ok(f"{s.get('name', '?')}  ←  {s.get('source', '')}")
+        return 0
+
+    results = skills.sync_skills(root)
+    if not results:
+        render.info("no hay skills declaradas en .tramalia/skills.toml (todas comentadas).")
+        return 0
+    for name, act in results:
+        ok = act in ("clonada", "actualizada")
+        (render.ok if ok else render.warn)(f"{act:>12}  {name}")
+    return 0
+
+
+def cmd_update(args) -> int:
+    from tramalia.core import skills
+    render.info("update = mise upgrade + skills sync (+ copier update, futuro)")
+    code = 0
+    if shutil.which("mise"):
+        code |= _run(["mise", "upgrade"])
+    else:
+        render.warn("mise ausente; omitiendo `mise upgrade`.")
+    results = skills.sync_skills(Path.cwd())
+    if results:
+        for name, act in results:
+            ok = act in ("clonada", "actualizada")
+            (render.ok if ok else render.warn)(f"skill {act}: {name}")
+    else:
+        render.info("sin skills externas declaradas que sincronizar.")
+    return code
+
+
+def cmd_mcp(args) -> int:
+    try:
+        import mcp  # noqa: F401
+    except ImportError:
+        render.err('falta el SDK MCP. Instálalo con: pip install "tramalia-cli[mcp]"')
+        return 127
+    from tramalia import mcp_server
+    render.info("levantando Tramalia MCP (stdio)… Ctrl+C para detener.")
+    mcp_server.run()
+    return 0
+
+
+def cmd_ui(args) -> int:
+    try:
+        import textual  # noqa: F401
+    except ImportError:
+        render.err('falta Textual. Instálalo con: pip install "tramalia-cli[tui]"')
+        return 127
+    from tramalia import tui
+    tui.run()
+    return 0
+
+
+def _guided_args(command: str):
+    """Prompts guiados para close/handoff/evidence desde el menú (modo novato).
+
+    Prellena con los defaults reales del proyecto: current-task.md y config.json.
+    """
+    import argparse
+    from tramalia.core import project
+    root = Path.cwd()
+    primary, rev = project.default_agents(root)
+    task = menu.ask_text("ID de la tarea (ver specs/tasks.md)",
+                         project.current_task_id(root) or "TASK-001")
+    agent = reviewer = ""
+    if command in ("close", "handoff"):
+        agent = menu.ask_text("agente ejecutor", primary or "codex")
+        reviewer = menu.ask_text("agente revisor sugerido", rev or "claude")
+    return argparse.Namespace(task=task, task_pos=None, agent=agent, reviewer=reviewer,
+                              engram=False, allow_fail=False)
+
+
+def _show_last_close(root: Path) -> None:
+    from tramalia.core import governance
+    entries = governance.read_log(root)
+    if entries:
+        last = entries[0]
+        mark = _LOG_MARKS.get(last.get("status"), "○ —")
+        render.info(f"último cierre: {last['id']}  ·  {mark}")
+
+
+def cmd_menu(args) -> int:
+    root = Path.cwd()
+    while True:
+        stack = detect_stack(root)
+        render.header(root.name, stack, _is_initialized(root))
+        _show_last_close(root)
+        try:
+            choice = menu.choose()
+        except (KeyboardInterrupt, EOFError):
+            return 0
+        if choice == "quit":
+            return 0
+        run_args = _guided_args(choice) if choice in ("close", "handoff", "evidence") else args
+        try:
+            dispatch(choice, run_args)
+        except (KeyboardInterrupt, EOFError):
+            render.warn("acción cancelada.")
+        print()
+
+
+_HANDLERS = {
+    "doctor": cmd_doctor,
+    "detect": cmd_detect,
+    "init": cmd_init,
+    "gates": cmd_gates,
+    "context": cmd_context,
+    "evidence": cmd_evidence,
+    "handoff": cmd_handoff,
+    "close": cmd_close,
+    "log": cmd_log,
+    "sync": cmd_sync,
+    "skills": cmd_skills,
+    "update": cmd_update,
+    "mcp": cmd_mcp,
+    "ui": cmd_ui,
+    "menu": cmd_menu,
+}
+
+
+def dispatch(command: str, args) -> int:
+    handler = _HANDLERS.get(command)
+    if handler is None:
+        render.err(f"comando desconocido: {command}")
+        return 2
+    return handler(args)

tramalia/cli/menu.py

@@ -0,0 +1,56 @@
+"""Menú interactivo: usa questionary si está; si no, menú numerado stdlib."""
+
+from __future__ import annotations
+
+try:
+    import questionary
+    _HAS_Q = True
+except Exception:
+    _HAS_Q = False
+
+# (clave, etiqueta) — la clave es el comando que se ejecuta
+OPTIONS: list[tuple[str, str]] = [
+    ("close", "★ cerrar tarea: gates → evidence → handoff"),
+    ("log", "ver pista de auditoría (cierres)"),
+    ("doctor", "diagnosticar herramientas requeridas"),
+    ("detect", "detectar el stack del proyecto"),
+    ("init", "inicializar o reparar la estructura"),
+    ("gates", "ejecutar quality gates (mise run gates)"),
+    ("context", "generar contexto / token-saver (repomix + serena)"),
+    ("evidence", "generar evidence pack"),
+    ("handoff", "crear handoff multiagente"),
+    ("sync", "sincronizar reglas a otros agentes (rulesync)"),
+    ("skills", "administrar skills (sync desde sus repos)"),
+    ("update", "actualizar todo (mise + skills)"),
+    ("ui", "abrir dashboard (TUI)"),
+    ("quit", "salir"),
+]
+
+
+def ask_text(prompt: str, default: str = "") -> str:
+    """Pregunta un texto (questionary si está; input stdlib si no)."""
+    if _HAS_Q:
+        answer = questionary.text(prompt, default=default, qmark="?").ask()
+        return (answer if answer is not None else default).strip() or default
+    raw = input(f"{prompt} [{default}]> ").strip()
+    return raw or default
+
+
+def choose() -> str:
+    if _HAS_Q:
+        answer = questionary.select(
+            "¿qué quieres hacer?",
+            choices=[questionary.Choice(title=label, value=key) for key, label in OPTIONS],
+            qmark="?",
+            instruction="(↑↓ navegar · ⏎ seleccionar)",
+        ).ask()
+        return answer or "quit"
+
+    # fallback stdlib
+    print("\n¿qué quieres hacer?")
+    for i, (_, label) in enumerate(OPTIONS, 1):
+        print(f"  {i:>2}. {label}")
+    raw = input("opción> ").strip()
+    if not raw.isdigit() or not (1 <= int(raw) <= len(OPTIONS)):
+        return "quit"
+    return OPTIONS[int(raw) - 1][0]

tramalia/cli/render.py

@@ -0,0 +1,133 @@
+"""Render con Rich si está disponible; si no, texto plano (terminal básica).
+
+Así la CLI corre sin instalar nada y se ve bonita automáticamente cuando
+instalas el extra `pretty` (rich + questionary).
+"""
+
+from __future__ import annotations
+
+from tramalia.core.doctor import Report
+
+_PLAIN = False
+
+try:  # modo bonito opcional
+    from rich.console import Console
+    from rich.table import Table
+    from rich.panel import Panel
+    from rich import box
+    _console: "Console | None" = Console()
+    _HAS_RICH = True
+except Exception:  # pragma: no cover - fallback stdlib
+    _console = None
+    _HAS_RICH = False
+
+
+def set_plain(value: bool) -> None:
+    global _PLAIN
+    _PLAIN = value
+
+
+def _rich() -> bool:
+    return _HAS_RICH and not _PLAIN
+
+
+_NEED = {"bootstrap": "base", "stack": "stack"}
+
+
+def _need_label(tool) -> str:
+    if tool.category == "feature":
+        return f"gate:{tool.feature}"
+    return _NEED.get(tool.category, tool.category)
+
+
+def header(project: str, stack: list[str], initialized: bool) -> None:
+    estado = "inicializado" if initialized else "no inicializado"
+    stack_txt = " · ".join(stack) if stack else "—"
+    if _rich():
+        _console.print(Panel(
+            f"proyecto [bold]{project}[/bold]   stack [bold]{stack_txt}[/bold]   "
+            f"estado [{'green' if initialized else 'yellow'}]{estado}[/]",
+            title="Tramalia", border_style="cyan", box=box.ROUNDED,
+        ))
+    else:
+        print("=" * 60)
+        print(f"Tramalia · proyecto {project} · stack {stack_txt} · {estado}")
+        print("=" * 60)
+
+
+def doctor(report: Report) -> int:
+    """Imprime el diagnóstico. Devuelve el exit code (0 si nada bloqueante falta)."""
+    stack_txt = " · ".join(report.stack) if report.stack else "—"
+    if _rich():
+        table = Table(box=box.SIMPLE_HEAVY, expand=False)
+        table.add_column("herramienta", style="bold")
+        table.add_column("necesidad", style="dim")
+        table.add_column("estado")
+        table.add_column("detalle / cómo obtenerla", overflow="fold")
+        for s in report.statuses:
+            if s.present:
+                estado = "[green]✓ ok[/green]"
+                detalle = s.version or "(instalada)"
+            elif s.tool.category == "feature":
+                estado = "[yellow]○ opcional[/yellow]"
+                detalle = s.tool.install_hint
+            else:
+                estado = "[red]✗ falta[/red]"
+                detalle = s.tool.install_hint
+            if s.tool.runtime == "node":
+                detalle += "  [magenta]· requiere Node[/magenta]"
+            table.add_row(s.tool.cmd, _need_label(s.tool), estado, detalle)
+        _console.print(f"\n[dim]stack detectado:[/dim] {stack_txt}")
+        _console.print(table)
+    else:
+        print(f"\nstack detectado: {stack_txt}")
+        print(f"{'herramienta':<14}{'necesidad':<16}{'estado':<11}detalle")
+        print("-" * 78)
+        for s in report.statuses:
+            if s.present:
+                estado, detalle = "ok", (s.version or "(instalada)")
+            elif s.tool.category == "feature":
+                estado, detalle = "opcional", s.tool.install_hint
+            else:
+                estado, detalle = "FALTA", s.tool.install_hint
+            if s.tool.runtime == "node":
+                detalle += "  · requiere Node"
+            print(f"{s.tool.cmd:<14}{_need_label(s.tool):<16}{estado:<11}{detalle}")
+
+    if report.needs_node:
+        _warn(f"Node no está instalado y lo requieren: {', '.join(report.node_tools)}.")
+        _info("instálalo con `mise use node@22` (o nvm) para usar sync / ux / context completo.")
+
+    blocking = report.missing_blocking
+    optional = report.missing_optional
+    if blocking:
+        names = ", ".join(s.tool.cmd for s in blocking)
+        _warn(f"faltan herramientas requeridas: {names}")
+        _info("instálalas con los comandos de arriba y vuelve a correr `tramalia doctor`.")
+        _info("una vez que tengas mise, el resto se instala con `mise install`.")
+        return 1
+    if optional:
+        names = ", ".join(s.tool.cmd for s in optional)
+        _info(f"opcionales ausentes (se activan al usar su gate): {names}")
+    _ok("todo lo requerido está presente.")
+    return 0
+
+
+def _ok(msg: str) -> None:
+    _console.print(f"[green]✓[/green] {msg}") if _rich() else print(f"[ok] {msg}")
+
+
+def _warn(msg: str) -> None:
+    _console.print(f"[yellow]▲[/yellow] {msg}") if _rich() else print(f"[!] {msg}")
+
+
+def _info(msg: str) -> None:
+    _console.print(f"[cyan]i[/cyan] {msg}") if _rich() else print(f"[i] {msg}")
+
+
+def _err(msg: str) -> None:
+    _console.print(f"[red]✗[/red] {msg}") if _rich() else print(f"[x] {msg}")
+
+
+# alias públicos
+ok, warn, info, err = _ok, _warn, _info, _err