klapcontext 0.3.3__tar.gz → 0.5.0__tar.gz

{klapcontext-0.3.3/src/klapcontext.egg-info → klapcontext-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klapcontext
-Version: 0.3.3
+Version: 0.5.0
 Summary: Make your repository understandable to humans and AI.
 Author: Willy Cordon
 License-Expression: Apache-2.0
@@ -78,9 +78,29 @@ klap init
 klap open
 ```
 
-`klap init` genera el análisis Graphify y escribe artefactos locales bajo
-`.klap/`. KlapContext agrega esa carpeta a `.git/info/exclude`; nunca modifica
-tu `.gitignore`.
+`klap init` genera el análisis Graphify, escribe artefactos locales bajo
+`.klap/` y prepara un `AGENTS.md` privado para que los agentes descubran el
+contexto progresivamente. Ambos se agregan a `.git/info/exclude`; KlapContext
+nunca modifica tu `.gitignore`.
+
+Para compartir las instrucciones de onboarding con el equipo:
+
+```bash
+klap init --shared
+```
+
+El modo compartido genera un `AGENTS.md` versionable, sin rutas personales ni
+secretos. Si el archivo ya existe, KlapContext preserva su contenido y sólo
+administra el bloque entre `KLAPCONTEXT:START` y `KLAPCONTEXT:END`. Un archivo
+versionado nunca se modifica silenciosamente en modo privado.
+
+El portal incluye un árbol navegable de archivos y símbolos extraídos del grafo,
+recorridos de llamadas y cambios recientes de Git. El contexto del agente y
+`klap context` usan las mismas rutas y símbolos. El indicador de cobertura cuenta
+archivos de código con al menos un nodo en Graphify: **no mide exhaustividad de
+funciones ni garantiza que se hayan resuelto rutas dinámicas**. Los recorridos
+son caminos del grafo, no afirmaciones de que una ruta HTTP los ejecuta; sus
+ramas pueden requerir inspección del código original.
 
 ## Comandos
 
@@ -92,6 +112,7 @@ tu `.gitignore`.
 | `klap open [ruta]` | Abre el portal humano estático. |
 | `klap agent [ruta]` | Muestra la configuración MCP local de Graphify. |
 | `klap context "tarea" [ruta]` | Compila un contexto focalizado reutilizando `.klap/context.json` si existe. |
+| `klap doctor --agent [ruta]` | Comprueba AGENTS.md, freshness, Graphify y configuración MCP. |
 | `klap --version` | Muestra la versión instalada. |
 
 ## Salidas
@@ -102,9 +123,15 @@ tu `.gitignore`.
 ├── agent-context.md      # briefing para agentes de IA
 ├── index.html            # portal humano, sin servidor
 ├── state.json            # metadatos de freshness
+├── mcp/                  # configuración local reutilizable para clientes MCP
 └── graphify/             # grafo, informe y visualizaciones de Graphify
 ```
 
+`klap agent` genera ejemplos locales para Codex, Claude Code, Cursor y clientes
+MCP genéricos. No instala agentes ni modifica configuraciones globales. Usá
+`klap doctor --agent --probe-mcp` para comprobar que Graphify MCP puede iniciar;
+eso no equivale a verificar una conexión real de un cliente.
+
 Las afirmaciones incluyen evidencia y estados `CONFIRMED`, `INFERRED` o
 `UNKNOWN`. Si KlapContext no puede determinar algo con confianza, lo expone en
 lugar de inventarlo.

{klapcontext-0.3.3 → klapcontext-0.5.0}/README.md

@@ -44,9 +44,29 @@ klap init
 klap open
 ```
 
-`klap init` genera el análisis Graphify y escribe artefactos locales bajo
-`.klap/`. KlapContext agrega esa carpeta a `.git/info/exclude`; nunca modifica
-tu `.gitignore`.
+`klap init` genera el análisis Graphify, escribe artefactos locales bajo
+`.klap/` y prepara un `AGENTS.md` privado para que los agentes descubran el
+contexto progresivamente. Ambos se agregan a `.git/info/exclude`; KlapContext
+nunca modifica tu `.gitignore`.
+
+Para compartir las instrucciones de onboarding con el equipo:
+
+```bash
+klap init --shared
+```
+
+El modo compartido genera un `AGENTS.md` versionable, sin rutas personales ni
+secretos. Si el archivo ya existe, KlapContext preserva su contenido y sólo
+administra el bloque entre `KLAPCONTEXT:START` y `KLAPCONTEXT:END`. Un archivo
+versionado nunca se modifica silenciosamente en modo privado.
+
+El portal incluye un árbol navegable de archivos y símbolos extraídos del grafo,
+recorridos de llamadas y cambios recientes de Git. El contexto del agente y
+`klap context` usan las mismas rutas y símbolos. El indicador de cobertura cuenta
+archivos de código con al menos un nodo en Graphify: **no mide exhaustividad de
+funciones ni garantiza que se hayan resuelto rutas dinámicas**. Los recorridos
+son caminos del grafo, no afirmaciones de que una ruta HTTP los ejecuta; sus
+ramas pueden requerir inspección del código original.
 
 ## Comandos
 
@@ -58,6 +78,7 @@ tu `.gitignore`.
 | `klap open [ruta]` | Abre el portal humano estático. |
 | `klap agent [ruta]` | Muestra la configuración MCP local de Graphify. |
 | `klap context "tarea" [ruta]` | Compila un contexto focalizado reutilizando `.klap/context.json` si existe. |
+| `klap doctor --agent [ruta]` | Comprueba AGENTS.md, freshness, Graphify y configuración MCP. |
 | `klap --version` | Muestra la versión instalada. |
 
 ## Salidas
@@ -68,9 +89,15 @@ tu `.gitignore`.
 ├── agent-context.md      # briefing para agentes de IA
 ├── index.html            # portal humano, sin servidor
 ├── state.json            # metadatos de freshness
+├── mcp/                  # configuración local reutilizable para clientes MCP
 └── graphify/             # grafo, informe y visualizaciones de Graphify
 ```
 
+`klap agent` genera ejemplos locales para Codex, Claude Code, Cursor y clientes
+MCP genéricos. No instala agentes ni modifica configuraciones globales. Usá
+`klap doctor --agent --probe-mcp` para comprobar que Graphify MCP puede iniciar;
+eso no equivale a verificar una conexión real de un cliente.
+
 Las afirmaciones incluyen evidencia y estados `CONFIRMED`, `INFERRED` o
 `UNKNOWN`. Si KlapContext no puede determinar algo con confianza, lo expone en
 lugar de inventarlo.

{klapcontext-0.3.3 → klapcontext-0.5.0}/src/klapcontext/__init__.py

@@ -1,3 +1,3 @@
 """KlapContext local engineering-context generator."""
 
-__version__ = "0.3.3"
+__version__ = "0.5.0"

{klapcontext-0.3.3 → klapcontext-0.5.0}/src/klapcontext/agent/compiler.py

@@ -34,8 +34,11 @@ def compile_context(root: Path, query: str, *, detail: str = "standard", max_tok
         context = build(root, {"nodes": []})
     model = context["system_model"]; limit = min(DETAIL_LIMITS[detail], max(1, max_tokens // 350)); terms = _terms(query, plan.area)
     entries = _rank(model["entry_points"], terms, limit); flows = _rank(model["main_flows"], terms, limit); files = _rank(model["important_files"], terms, limit)
-    read_first = ([{"path": item.get("file"), "reason": "Punto de entrada relacionado", "relevance": item["relevance"]} for item in entries if item.get("file")] + files)[:limit]
-    result = {"intent": plan.intent, "confidence": plan.confidence, "query": query, "area": plan.area, "detail": detail, "max_tokens": max_tokens, "entry_points": entries, "flows": flows, "symbols": _rank(model["semantic_model"]["components"], terms, limit), "files": files, "dependencies": _rank(model["dependencies"], terms, limit), "tests": _rank(context["tests"], terms, limit), "read_first": read_first, "evidence": [evidence for group in entries + flows for evidence in group.get("evidence", [])][:limit], "uncertainties": model["unknowns"], "strategy": plan.strategy}
+    exploration = model.get("exploration", {})
+    graph_files = _rank(exploration.get("files", []), terms, limit)
+    graph_paths = _rank(exploration.get("call_paths", []), terms, limit)
+    read_first = ([{"path": item.get("file"), "reason": "Punto de entrada relacionado", "relevance": item["relevance"]} for item in entries if item.get("file")] + [{"path": item["path"], "reason": "Archivo o símbolo relacionado en el grafo", "relevance": item["relevance"]} for item in graph_files] + files)[:limit]
+    result = {"intent": plan.intent, "confidence": plan.confidence, "query": query, "area": plan.area, "detail": detail, "max_tokens": max_tokens, "entry_points": entries, "flows": flows, "graph_call_paths": graph_paths, "symbols": _rank(model["semantic_model"]["components"], terms, limit), "files": files + graph_files, "coverage": exploration.get("coverage", {}), "recent_changes": _rank(model.get("recent_changes", []), terms, min(limit, 3)), "dependencies": _rank(model["dependencies"], terms, limit), "tests": _rank(context["tests"], terms, limit), "read_first": read_first, "evidence": [evidence for group in entries + flows for evidence in group.get("evidence", [])][:limit], "uncertainties": model["unknowns"], "strategy": plan.strategy}
     result["verification"] = reconcile(result["evidence"])
     result = sanitize(result)
     result["estimated_tokens"] = min(max_tokens, len(json.dumps(result, ensure_ascii=False)) // 4)

{klapcontext-0.3.3 → klapcontext-0.5.0}/src/klapcontext/agent_context.py

@@ -5,9 +5,15 @@ def items(values, key="name"):
     return "\n".join(f"- {value.get(key) or value.get('path')}" for value in values) if values else "Sin evidencia disponible."
 def render(context: dict) -> str:
     s=context.get("system_model",{}); purpose=s.get("purpose",{}).get("text") or "No fue posible determinar el propósito con confianza."
+    exploration=s.get("exploration",{}); coverage=exploration.get("coverage",{})
     sections=[("Propósito del Proyecto",purpose),("Cómo Funciona el Sistema",s.get("project_story",{}).get("text") or "No fue posible determinarlo con confianza."),("Superficies de Ejecución","\n".join(f"- {x['label']}: {x['count']}" for x in s.get("runtime_surfaces",[])) or "Sin superficies específicas detectadas."),("Rutas",items(s.get("routes",[]))),("Procesos Programados",items(s.get("scheduled_processes",[]))),("Jobs de Cola",items(s.get("queue_jobs",[]))),("Flujos Principales","\n".join(f"- **{x['name']}**: " + " → ".join(step["name"] for step in x["steps"]) for x in s.get("main_flows",[])) or "No se detectaron flujos principales con confianza."),("Dependencias Importantes","\n".join(f"- {x['package']} {x['version']} ({x['scope']})" for x in s.get("dependencies",[])[:12]) or "Sin dependencias específicas detectadas."),("Sistemas Externos",items(s.get("external_systems",[]))),("Almacenes de Datos",items(s.get("datastores",[]))),("Por Dónde Empezar","\n".join(f"- **{x['intent']}**: {', '.join(x['paths'])}" for x in s.get("start_here",[])) or "Sin recomendaciones detectadas."),("Incertidumbres","\n".join(f"- {x}" for x in s.get("unknowns",[])) or "Sin incertidumbres relevantes registradas.")]
     lines=["# KlapContext — Contexto del Proyecto"]
     for title,body in sections: lines.extend(["",f"## {title}",body])
+    lines.extend(["", "## Cobertura de la exploración", f"- Archivos de código con nodos: {coverage.get('code_files_with_graph_nodes', 0)}/{coverage.get('eligible_code_files', 0)}; estado: {coverage.get('status', 'UNKNOWN')}.", "- Un archivo representado en el grafo no implica que todas sus funciones estén resueltas.", "", "## Estructura y recorridos de llamadas", "- Consulta `.klap/context.json` → `system_model.exploration.files` para localizar archivos y símbolos por ruta."])
+    for path in exploration.get("call_paths", [])[:8]:
+        lines.append("- " + " → ".join(f"{step['name']} ({step['file']})" for step in path["steps"]) + " [recorrido del grafo; entrada no confirmada]")
+    lines.extend(["", "## Cambios recientes en Git"])
+    lines.extend(f"- {change['date']} {change['commit'][:10]}: {change['subject']}" for change in s.get("recent_changes", [])[:6])
     lines.extend(["","## Instrucciones para el Agente","1. Lee este contexto antes de explorar ampliamente el repositorio.","2. Usa Graphify MCP para dependencias y rutas de llamadas.","3. Consulta paths o vecinos relevantes antes de abrir muchos archivos.","4. Lee el código real antes de modificarlo.","5. Trata el contexto inferido como guía, no como verdad absoluta."])
     text="\n".join(lines)+"\n"; return text+f"\nTokens estimados: {len(text.split()) * 4 // 3}\n"
 def write(context: dict, output: Path) -> str:

klapcontext-0.5.0/src/klapcontext/agent_setup.py

@@ -0,0 +1,264 @@
+"""Safe, idempotent onboarding for AGENTS.md-compatible coding agents."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .git import commit, dirty_files, is_repository, run_git
+from .graphify import command_prefix
+
+START = "<!-- KLAPCONTEXT:START -->"
+END = "<!-- KLAPCONTEXT:END -->"
+AGENT_FILE = "AGENTS.md"
+
+
+@dataclass
+class AgentSetupResult:
+    status: str
+    path: str = AGENT_FILE
+    mode: str = "private"
+    created: bool = False
+    updated: bool = False
+    tracked: bool = False
+    mcp_configured: bool = False
+    message: str = ""
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def is_tracked(root: Path, relative: str = AGENT_FILE) -> bool:
+    return is_repository(root) and run_git(root, "ls-files", "--error-unmatch", relative) is not None
+
+
+def marker_state(text: str) -> str:
+    starts, ends = text.count(START), text.count(END)
+    if starts == ends == 0:
+        return "absent"
+    if starts == ends == 1 and text.index(START) < text.index(END):
+        return "valid"
+    return "malformed"
+
+
+def context_freshness(root: Path) -> dict:
+    state_file = root / ".klap" / "state.json"
+    if not state_file.exists():
+        return {"status": "MISSING", "reason": "No existe .klap/state.json"}
+    try:
+        state = json.loads(state_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"status": "INVALID", "reason": "state.json no es válido"}
+    current = commit(root)
+    ignored = (".klap/", "graphify-out/", AGENT_FILE)
+    relevant = [path for path in dirty_files(root) if not path.replace("\\", "/").startswith(ignored)]
+    if state.get("git_commit") != current:
+        return {"status": "STALE", "reason": "El commit analizado no coincide con HEAD", "changed_files": relevant}
+    if relevant:
+        return {"status": "STALE", "reason": "Hay cambios relevantes sin confirmar", "changed_files": relevant}
+    return {"status": "CURRENT", "reason": "El contexto coincide con el código confirmado", "changed_files": []}
+
+
+def generate_mcp_configs(root: Path) -> dict:
+    """Write local examples only; never mutate global agent configuration."""
+    graph = (root / ".klap" / "graphify" / "graph.json").resolve()
+    directory = root / ".klap" / "mcp"
+    directory.mkdir(parents=True, exist_ok=True)
+    prefix = command_prefix()
+    available = bool(prefix and graph.exists())
+    command = sys.executable
+    args = ["-m", "graphify.serve", str(graph)]
+    generic = {"mcpServers": {"graphify": {"command": command, "args": args}}}
+    (directory / "generic.json").write_text(json.dumps(generic, indent=2) + "\n", encoding="utf-8")
+    codex = "[mcp_servers.graphify]\n" + f'command = {json.dumps(command)}\nargs = {json.dumps(args)}\n'
+    (directory / "codex.toml").write_text(codex, encoding="utf-8")
+    instructions = f"""# Graphify MCP setup
+
+Generated local configuration examples. They contain no credentials.
+
+- Generic / Claude Code project config: `.klap/mcp/generic.json`
+- Cursor project config: copy the same JSON to `.cursor/mcp.json` only when you explicitly want project configuration.
+- Codex project config snippet: `.klap/mcp/codex.toml`
+
+The configured stdio command is:
+
+`{command} {' '.join(args)}`
+
+Run `klap doctor --agent --probe-mcp` to verify that the server can start. A configuration file alone does not prove a client connection.
+"""
+    (directory / "README.md").write_text(instructions, encoding="utf-8")
+    return {"available": available, "directory": ".klap/mcp", "generic": ".klap/mcp/generic.json", "codex": ".klap/mcp/codex.toml"}
+
+
+def _overview(context: dict) -> str:
+    project = context.get("project", {})
+    system = context.get("system_model", {})
+    stack = context.get("stack", {})
+    purpose = system.get("purpose", {}).get("text")
+    languages = ", ".join(stack.get("languages", []))
+    frameworks = ", ".join(stack.get("frameworks", []))
+    facts = [f"Repository `{project.get('name', 'project')}`"]
+    if languages:
+        facts.append(f"uses {languages}")
+    if frameworks:
+        facts.append(f"with {frameworks}")
+    summary = " ".join(facts) + "."
+    if purpose:
+        summary += " " + purpose.strip()
+    flows = system.get("main_flows", [])
+    if flows:
+        summary += f" KlapContext detected {len(flows)} main execution flow(s)."
+    return summary
+
+
+def render_agent_block(context: dict, *, shared: bool) -> str:
+    shared_note = "\nIf `.klap/` is missing, run `klap init` before relying on generated context.\n" if shared else ""
+    return f"""{START}
+
+## KlapContext — Engineering Context
+
+This repository has been analyzed by KlapContext.
+
+### Project overview
+
+{_overview(context)}
+{shared_note}
+### Before starting a task
+
+1. Run `klap status`; if relevant context is stale, run `klap update`.
+2. Read `.klap/agent-context.md` progressively; do not load the entire graph.
+3. Use Graphify MCP for dependencies, call paths, callers and impact analysis.
+4. Identify the relevant execution flow before modifying code.
+5. Read the actual source code and related tests before making changes.
+6. Treat inferred relationships as hypotheses until verified.
+
+### Context resources
+
+- `.klap/agent-context.md`
+- `.klap/context.json`
+- `.klap/index.html`
+- `.klap/graphify/graph.json`
+- `.klap/mcp/README.md`
+
+### Working rules
+
+- Respect existing architecture, conventions and contracts.
+- Prefer focused Graphify queries over broad repository searches.
+- Never modify code based only on generated context; verify the source first.
+- Preserve existing contracts unless the task explicitly requires changing them.
+
+{END}"""
+
+
+class AgentInstructionsManager:
+    def __init__(self, root: Path):
+        self.root = root.resolve()
+        self.path = self.root / AGENT_FILE
+
+    def apply(self, context: dict, *, shared: bool = False, allow_tracked: bool = False) -> AgentSetupResult:
+        mode = "shared" if shared else "private"
+        tracked = is_tracked(self.root)
+        if tracked and not (shared or allow_tracked):
+            return AgentSetupResult("authorization_required", mode=mode, tracked=True, message="AGENTS.md está versionado; se requiere autorización explícita.")
+        existing = self.path.read_text(encoding="utf-8") if self.path.exists() else ""
+        state = marker_state(existing)
+        if state == "malformed":
+            return AgentSetupResult("conflict", mode=mode, tracked=tracked, message="Marcadores KLAPCONTEXT incompletos o duplicados; no se modificó AGENTS.md.")
+        block = render_agent_block(context, shared=shared)
+        if state == "valid":
+            start = existing.index(START)
+            end = existing.index(END, start) + len(END)
+            updated = existing[:start] + block + existing[end:]
+        elif existing.strip():
+            updated = existing.rstrip() + "\n\n" + block + "\n"
+        else:
+            updated = block + "\n"
+        if updated == existing:
+            if shared:
+                self._include_shared_agents()
+            return AgentSetupResult("unchanged", mode=mode, tracked=tracked, mcp_configured=True, message="AGENTS.md ya está actualizado.")
+        self._atomic_write(updated, existing if self.path.exists() else None)
+        if shared:
+            self._include_shared_agents()
+        elif not tracked and is_repository(self.root):
+            self._exclude_private_agents()
+        return AgentSetupResult("configured", mode=mode, created=not bool(existing), updated=bool(existing), tracked=tracked, mcp_configured=True, message="AGENTS.md configurado de forma segura.")
+
+    def _atomic_write(self, content: str, previous: str | None) -> None:
+        if previous is not None:
+            backup = self.root / ".klap" / "backups" / AGENT_FILE
+            backup.parent.mkdir(parents=True, exist_ok=True)
+            backup.write_text(previous, encoding="utf-8")
+        fd, name = tempfile.mkstemp(prefix=".AGENTS.", suffix=".tmp", dir=self.root)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+                handle.write(content)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(name, self.path)
+        finally:
+            if os.path.exists(name):
+                os.unlink(name)
+
+    def _exclude_private_agents(self) -> None:
+        git_dir = run_git(self.root, "rev-parse", "--git-dir")
+        if not git_dir:
+            return
+        exclude = (self.root / git_dir / "info" / "exclude").resolve()
+        existing = exclude.read_text(encoding="utf-8") if exclude.exists() else ""
+        if AGENT_FILE not in {line.strip() for line in existing.splitlines()}:
+            exclude.write_text(existing.rstrip() + ("\n" if existing.strip() else "") + AGENT_FILE + "\n", encoding="utf-8")
+
+    def _include_shared_agents(self) -> None:
+        git_dir = run_git(self.root, "rev-parse", "--git-dir")
+        if not git_dir:
+            return
+        exclude = (self.root / git_dir / "info" / "exclude").resolve()
+        if not exclude.exists():
+            return
+        lines = exclude.read_text(encoding="utf-8").splitlines()
+        filtered = [line for line in lines if line.strip() != AGENT_FILE]
+        if filtered != lines:
+            exclude.write_text("\n".join(filtered).rstrip() + ("\n" if filtered else ""), encoding="utf-8")
+
+    def validate(self) -> dict:
+        if not self.path.exists():
+            return {"status": "missing", "valid": False, "message": "AGENTS.md no existe"}
+        text = self.path.read_text(encoding="utf-8")
+        state = marker_state(text)
+        paths = [".klap/agent-context.md", ".klap/context.json", ".klap/index.html", ".klap/graphify/graph.json"]
+        missing = [path for path in paths if not (self.root / path).exists()]
+        return {"status": state, "valid": state == "valid" and not missing, "missing_paths": missing, "message": "Configuración válida" if state == "valid" and not missing else "Configuración incompleta"}
+
+
+def probe_graphify_mcp(root: Path, timeout: float = 2.0) -> dict:
+    graph = root / ".klap" / "graphify" / "graph.json"
+    prefix = command_prefix()
+    if not prefix or not graph.exists():
+        return {"startable": False, "connection_verified": False, "reason": "Graphify o graph.json no disponible"}
+    command = [sys.executable, "-m", "graphify.serve", str(graph)]
+    process = subprocess.Popen(command, cwd=root, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    try:
+        process.wait(timeout=timeout)
+        return {"startable": process.returncode == 0, "connection_verified": False, "reason": "El proceso terminó sin una sesión MCP"}
+    except subprocess.TimeoutExpired:
+        process.terminate()
+        try:
+            process.wait(timeout=1)
+        except subprocess.TimeoutExpired:
+            process.kill()
+        return {"startable": True, "connection_verified": False, "reason": "El servidor inició; no se verificó conexión de un cliente"}
+
+
+def doctor_agent(root: Path, *, probe_mcp: bool = False) -> dict:
+    manager = AgentInstructionsManager(root)
+    agents = manager.validate()
+    freshness = context_freshness(root)
+    graph = root / ".klap" / "graphify" / "graph.json"
+    mcp_files = [root / ".klap" / "mcp" / "generic.json", root / ".klap" / "mcp" / "codex.toml"]
+    mcp_probe = probe_graphify_mcp(root) if probe_mcp else {"startable": bool(command_prefix() and graph.exists()), "connection_verified": False, "reason": "Use --probe-mcp para comprobar el arranque"}
+    return {"agents": agents, "context": {"available": (root / ".klap" / "agent-context.md").exists() and (root / ".klap" / "context.json").exists()}, "freshness": freshness, "graph": {"available": graph.exists()}, "mcp": {"configured": all(path.exists() for path in mcp_files), **mcp_probe}}

klapcontext-0.5.0/src/klapcontext/cli.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+import argparse, json, os, sys, webbrowser
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from .agent_context import write as write_agent
+from .agent_setup import AgentInstructionsManager, context_freshness, doctor_agent, generate_mcp_configs, is_tracked
+from .context_builder import build
+from .git import commit, dirty_files, exclude_klap, is_repository
+from .graphify import GraphifyError
+from .portal import write as write_portal
+from .providers import default_provider
+
+
+def root_path(value: str | None) -> Path:
+    return Path(value or os.getcwd()).resolve()
+
+
+def generate_all(root: Path, update: bool = False, *, shared: bool = False, allow_tracked_agents: bool = False) -> dict:
+    if not is_repository(root):
+        raise RuntimeError(f"Not a Git repository: {root}")
+    exclude_klap(root)
+    klap = root / ".klap"
+    klap.mkdir(exist_ok=True)
+    provider = default_provider()
+    graph_path = provider.generate(root, update)
+    files = provider.copy_outputs(root, klap / "graphify")
+    context = build(root, provider.load_graph(graph_path))
+    (klap / "context.json").write_text(json.dumps(context, indent=2) + "\n", encoding="utf-8")
+    agent = write_agent(context, klap / "agent-context.md")
+    mcp = generate_mcp_configs(root)
+    setup = AgentInstructionsManager(root).apply(context, shared=shared, allow_tracked=allow_tracked_agents)
+    context["agent_onboarding"] = {**setup.as_dict(), "mcp": mcp}
+    (klap / "context.json").write_text(json.dumps(context, indent=2) + "\n", encoding="utf-8")
+    write_portal(context, agent, files, klap / "index.html")
+    state = {
+        "schema_version": "0.3",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "git_commit": commit(root),
+        "provider": {"name": provider.name, "version": provider.version()},
+        "klap_version": __version__,
+        "agent_onboarding": setup.as_dict(),
+    }
+    (klap / "state.json").write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
+    return context
+
+
+def _permission(args, root: Path, action: str) -> tuple[bool, bool]:
+    shared = getattr(args, "shared", False)
+    allow = getattr(args, "allow_tracked_agents", False)
+    if not shared and is_tracked(root) and not allow and sys.stdin.isatty():
+        allow = input(f"AGENTS.md está versionado. ¿{action} la sección KlapContext? [y/N] ").strip().lower() in {"y", "yes", "s", "si", "sí"}
+    return shared, allow
+
+
+def cmd_init(args):
+    root = root_path(args.path)
+    print("KlapContext\n")
+    shared, allow = _permission(args, root, "Agregar o actualizar")
+    try:
+        context = generate_all(root, shared=shared, allow_tracked_agents=allow) if shared or allow else generate_all(root)
+    except (RuntimeError, GraphifyError) as error:
+        print(f"✗ {error}", file=sys.stderr)
+        return 1
+    print("✓ Git repository detected\n✓ Graphify available\n✓ Graph generated\n✓ Engineering context generated\n✓ Agent context generated\n✓ Human portal generated")
+    setup = context.get("agent_onboarding", {})
+    print(("✓ " if setup.get("status") in {"configured", "unchanged"} else "! ") + setup.get("message", "Agent onboarding not configured"))
+    coverage = context["system_model"]["exploration"]["coverage"]
+    print(f"Coverage: {coverage['code_files_with_graph_nodes']}/{coverage['eligible_code_files']} code files represented in graph ({coverage['status']}); graph nodes do not guarantee complete symbol analysis")
+    stack_items = [item for values in context["stack"].values() if isinstance(values, list) for item in values]
+    print(f"\nProject: {context['project']['name']}\nStack: {' / '.join(stack_items) or 'unknown'}\nContext: CURRENT\n\nHuman portal:\n.klap/index.html\n\nAgent context:\n.klap/agent-context.md")
+    return 0
+
+
+def cmd_update(args):
+    root = root_path(args.path)
+    shared, allow = _permission(args, root, "Actualizar")
+    try:
+        context = generate_all(root, update=True, shared=shared, allow_tracked_agents=allow) if shared or allow else generate_all(root, update=True)
+    except (RuntimeError, GraphifyError) as error:
+        print(f"✗ {error}", file=sys.stderr)
+        return 1
+    coverage = context["system_model"]["exploration"]["coverage"]
+    print(f"✓ KlapContext updated; graph coverage: {coverage['code_files_with_graph_nodes']}/{coverage['eligible_code_files']} code files ({coverage['status']})")
+    return 0
+
+
+def cmd_status(args):
+    root = root_path(args.path)
+    state_file = root / ".klap" / "state.json"
+    if not state_file.exists():
+        print("! No KlapContext found. Run: klap init")
+        return 1
+    try:
+        state = json.loads(state_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        print("Status: INVALID\nstate.json no es válido")
+        return 2
+    current = commit(root)
+    ignored = (".klap/", "graphify-out/", "AGENTS.md")
+    relevant = [path for path in dirty_files(root) if not path.replace("\\", "/").startswith(ignored)]
+    fresh = state.get("git_commit") == current and not relevant
+    reason = "El contexto coincide con el código confirmado" if fresh else "El commit analizado o archivos relevantes cambiaron"
+    print(f"Status: {'CURRENT' if fresh else 'STALE'}\n{reason}")
+    return 0 if fresh else 2
+
+
+def cmd_doctor(args):
+    result = doctor_agent(root_path(args.path), probe_mcp=getattr(args, "probe_mcp", False))
+    print("KlapContext — Agent Doctor\n")
+    checks = [
+        (result["agents"]["valid"], "AGENTS.md configured"),
+        (result["context"]["available"], "Engineering context available"),
+        (result["freshness"]["status"] == "CURRENT", "Context is current"),
+        (result["graph"]["available"], "Graphify graph available"),
+        (result["mcp"]["configured"], "MCP configuration generated"),
+    ]
+    for ok, label in checks:
+        print(("✓" if ok else "!") + " " + label)
+    print(("✓" if result["mcp"]["connection_verified"] else "!") + " MCP connection " + ("verified" if result["mcp"]["connection_verified"] else "not yet verified"))
+    if result["agents"].get("missing_paths"):
+        print("Missing paths: " + ", ".join(result["agents"]["missing_paths"]))
+    return 0 if all(ok for ok, _ in checks) else 2
+
+
+def cmd_open(args):
+    page = root_path(args.path) / ".klap" / "index.html"
+    if not page.exists():
+        print("⚠ No human portal found. Run: klap init", file=sys.stderr)
+        return 1
+    webbrowser.open(page.as_uri())
+    print(f"Opened {page}")
+    return 0
+
+
+def cmd_agent(args):
+    root = root_path(args.path)
+    graph = root / ".klap" / "graphify" / "graph.json"
+    if not graph.exists():
+        print("⚠ No Graphify graph found. Run: klap init", file=sys.stderr)
+        return 1
+    config = generate_mcp_configs(root)
+    print(f"Graphify MCP setup generated in {config['directory']}\nGeneric: {config['generic']}\nCodex: {config['codex']}\nRun: klap doctor --agent --probe-mcp")
+    return 0
+
+
+def cmd_context(args):
+    from .agent.compiler import compile_context
+    result = compile_context(root_path(args.path), args.query, detail=args.detail, max_tokens=args.max_tokens)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"Intent: {result['intent']}\nÁrea: {result['area']}\nRead first:\n" + "\n".join(f"- {item.get('path', item.get('name'))}: {item['reason']}" for item in result["read_first"]))
+    return 0
+
+
+def main(argv=None):
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(prog="klap", description="Make your repository understandable to humans and AI.")
+    parser.add_argument("--version", action="version", version=__version__)
+    subs = parser.add_subparsers(dest="command", required=True)
+    for name, func, help_text in (("init", cmd_init, "Generate engineering context"), ("update", cmd_update, "Refresh engineering context"), ("status", cmd_status, "Show context freshness"), ("open", cmd_open, "Open the human portal"), ("agent", cmd_agent, "Show Graphify MCP setup")):
+        command = subs.add_parser(name, help=help_text)
+        command.add_argument("path", nargs="?", help="Repository root (defaults to current directory)")
+        if name in {"init", "update"}:
+            command.add_argument("--shared", action="store_true", help="Create versionable AGENTS.md instructions")
+            command.add_argument("--allow-tracked-agents", action="store_true", help="Authorize updating a tracked AGENTS.md")
+        command.set_defaults(func=func)
+    command = subs.add_parser("doctor", help="Diagnose project and agent readiness")
+    command.add_argument("path", nargs="?", default=".")
+    command.add_argument("--agent", action="store_true", help="Check AGENTS.md and generated context")
+    command.add_argument("--probe-mcp", action="store_true", help="Start Graphify MCP briefly and stop it")
+    command.set_defaults(func=cmd_doctor)
+    command = subs.add_parser("context", help="Compile compact context for an agent task")
+    command.add_argument("query")
+    command.add_argument("path", nargs="?", default=".")
+    command.add_argument("--detail", choices=("minimal", "standard", "deep"), default="standard")
+    command.add_argument("--max-tokens", type=int, default=5000)
+    command.add_argument("--json", action="store_true")
+    command.set_defaults(func=cmd_context)
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())