klapcontext 0.1.0__tar.gz

klapcontext-0.1.0/LICENSE

@@ -0,0 +1,44 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this
+      License, each contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies subject to
+      the conditions in the Apache License, Version 2.0.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      shall be under the terms and conditions of this License.
+
+   6. Trademarks. This License does not grant permission to use trade names,
+      trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any contributor be liable for damages arising from this License.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the
+      Work, You may choose to offer support, warranty, indemnity, or
+      liability obligations, but only on Your own behalf.

klapcontext-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: klapcontext
+Version: 0.1.0
+Summary: Make your repository understandable to humans and AI.
+Author: Willy Cordon
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/willy-cordon/klap_context
+Project-URL: Repository, https://github.com/willy-cordon/klap_context
+Project-URL: Issues, https://github.com/willy-cordon/klap_context/issues
+Keywords: codebase,developer-tools,engineering-context,graphify,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphifyy>=0.9.66
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# KlapContext
+
+Make your repository understandable to humans and AI.
+
+KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
+portal estático para personas y un briefing compacto para agentes de IA. Usa
+[Graphify](https://github.com/Graphify-Labs/graphify) como motor local de
+análisis técnico; KlapContext no reimplementa su grafo ni sus parsers.
+
+```text
+Repositorio → KlapContext → Contexto de ingeniería
+                              ├── Portal humano
+                              └── Contexto para agentes
+```
+
+## Instalación
+
+```bash
+pip install klapcontext
+```
+
+La instalación incluye `graphifyy`, la distribución oficial de Graphify que
+KlapContext necesita para generar el análisis local. Como alternativa para una
+CLI aislada: `pipx install klapcontext`.
+
+## Primer uso
+
+```bash
+cd mi-proyecto
+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`.
+
+## Comandos
+
+| Comando | Descripción |
+| --- | --- |
+| `klap init [ruta]` | Genera el contexto inicial. |
+| `klap update [ruta]` | Actualiza Graphify y el contexto. |
+| `klap status [ruta]` | Indica si el contexto está actualizado respecto a Git. |
+| `klap open [ruta]` | Abre el portal humano estático. |
+| `klap agent [ruta]` | Muestra la configuración MCP local de Graphify. |
+| `klap --version` | Muestra la versión instalada. |
+
+## Salidas
+
+```text
+.klap/
+├── context.json          # modelo técnico, de sistema y humano
+├── agent-context.md      # briefing para agentes de IA
+├── index.html            # portal humano, sin servidor
+├── state.json            # metadatos de freshness
+└── graphify/             # grafo, informe y visualizaciones de Graphify
+```
+
+Las afirmaciones incluyen evidencia y estados `CONFIRMED`, `INFERRED` o
+`UNKNOWN`. Si KlapContext no puede determinar algo con confianza, lo expone en
+lugar de inventarlo.
+
+## Desarrollo
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Publicación
+
+El workflow de GitHub Actions publica tags `v*` mediante PyPI Trusted
+Publishing. Antes del primer tag, configurá el publisher de PyPI para este
+repositorio y workflow. No se necesitan tokens de PyPI en el repositorio.
+
+## Licencia
+
+Apache-2.0. Ver [LICENSE](LICENSE).

klapcontext-0.1.0/README.md

@@ -0,0 +1,79 @@
+# KlapContext
+
+Make your repository understandable to humans and AI.
+
+KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
+portal estático para personas y un briefing compacto para agentes de IA. Usa
+[Graphify](https://github.com/Graphify-Labs/graphify) como motor local de
+análisis técnico; KlapContext no reimplementa su grafo ni sus parsers.
+
+```text
+Repositorio → KlapContext → Contexto de ingeniería
+                              ├── Portal humano
+                              └── Contexto para agentes
+```
+
+## Instalación
+
+```bash
+pip install klapcontext
+```
+
+La instalación incluye `graphifyy`, la distribución oficial de Graphify que
+KlapContext necesita para generar el análisis local. Como alternativa para una
+CLI aislada: `pipx install klapcontext`.
+
+## Primer uso
+
+```bash
+cd mi-proyecto
+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`.
+
+## Comandos
+
+| Comando | Descripción |
+| --- | --- |
+| `klap init [ruta]` | Genera el contexto inicial. |
+| `klap update [ruta]` | Actualiza Graphify y el contexto. |
+| `klap status [ruta]` | Indica si el contexto está actualizado respecto a Git. |
+| `klap open [ruta]` | Abre el portal humano estático. |
+| `klap agent [ruta]` | Muestra la configuración MCP local de Graphify. |
+| `klap --version` | Muestra la versión instalada. |
+
+## Salidas
+
+```text
+.klap/
+├── context.json          # modelo técnico, de sistema y humano
+├── agent-context.md      # briefing para agentes de IA
+├── index.html            # portal humano, sin servidor
+├── state.json            # metadatos de freshness
+└── graphify/             # grafo, informe y visualizaciones de Graphify
+```
+
+Las afirmaciones incluyen evidencia y estados `CONFIRMED`, `INFERRED` o
+`UNKNOWN`. Si KlapContext no puede determinar algo con confianza, lo expone en
+lugar de inventarlo.
+
+## Desarrollo
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Publicación
+
+El workflow de GitHub Actions publica tags `v*` mediante PyPI Trusted
+Publishing. Antes del primer tag, configurá el publisher de PyPI para este
+repositorio y workflow. No se necesitan tokens de PyPI en el repositorio.
+
+## Licencia
+
+Apache-2.0. Ver [LICENSE](LICENSE).

klapcontext-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "klapcontext"
+dynamic = ["version"]
+description = "Make your repository understandable to humans and AI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{name = "Willy Cordon"}]
+keywords = ["codebase", "developer-tools", "engineering-context", "graphify", "ai-agents"]
+classifiers = ["Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Topic :: Software Development :: Documentation"]
+dependencies = ["graphifyy>=0.9.66"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8", "twine>=6"]
+
+[project.urls]
+Homepage = "https://github.com/willy-cordon/klap_context"
+Repository = "https://github.com/willy-cordon/klap_context"
+Issues = "https://github.com/willy-cordon/klap_context/issues"
+
+[project.scripts]
+klap = "klapcontext.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.dynamic]
+version = {attr = "klapcontext.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

klapcontext-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

klapcontext-0.1.0/src/klapcontext/__init__.py

@@ -0,0 +1,3 @@
+"""KlapContext local engineering-context generator."""
+
+__version__ = "0.1.0"

klapcontext-0.1.0/src/klapcontext/agent_context.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+from pathlib import Path
+
+def listado(items: list[dict], key: str = "name") -> str:
+    return "\n".join(f"- {item.get(key) or item.get('path')}" for item in items) if items else "Sin evidencia disponible."
+def flujo(flow: dict) -> str:
+    return f"- **{flow['name']}** ({flow['status'].lower()}): " + " → ".join(step["name"] for step in flow["steps"])
+def render(context: dict) -> str:
+    system=context.get("system_model", {}); purpose=system.get("purpose", {}); story=system.get("project_story", {}); runtime=system.get("runtime", {})
+    lines=["# KlapContext — Contexto del Proyecto", "", "## Propósito del Proyecto", purpose.get("text") or "No fue posible determinar el propósito del proyecto con confianza.", "", "## Cómo Funciona el Sistema", story.get("text") or "No fue posible determinar el comportamiento del sistema con confianza.", "", "## Modelo de Ejecución", runtime.get("description") or "Modelo de ejecución desconocido.", "", "## Puntos de Entrada", listado(system.get("entry_points", [])), "", "## Flujos Principales", "\n".join(flujo(x) for x in system.get("main_flows", [])) or "No se detectaron flujos principales con confianza.", "", "## Capacidades Principales", listado(system.get("capabilities", [])), "", "## Entradas", listado(system.get("inputs", []), "description"), "", "## Salidas", listado(system.get("outputs", []), "description"), "", "## Sistemas Externos", listado(system.get("external_systems", [])), "", "## Almacenes de Datos", listado(system.get("datastores", [])), "", "## Procesos en Segundo Plano", listado(system.get("background_processes", [])), "", "## Despliegue", listado(system.get("deployment", {}).get("files", []), "path"), "", "## Observabilidad", listado(system.get("observability", {}).get("tools", [])), "", "## Pruebas", listado(context.get("tests", []), "path"), "", "## Por Dónde Empezar", "\n".join(f"- **{x['intent']}**: {', '.join(x['paths'])}" for x in system.get("start_here", [])) or "No se detectaron recomendaciones de onboarding con confianza.", "", "## Archivos Importantes", "\n".join(f"- `{x['path']}` — {x['role']}" for x in system.get("important_files", [])) or "No se detectaron archivos importantes.", "", "## Arquitectura Técnica", f"{context['architecture'].get('style') or 'Desconocida'} ({context['architecture'].get('status','UNKNOWN').lower()})", "", "## Incertidumbres", "\n".join(f"- {x}" for x in system.get("unknowns", [])) or "No hay incertidumbres relevantes registradas.", "", "## Instrucciones para el Agente", "1. Lee este contexto antes de explorar ampliamente el repositorio.", "2. Usa Graphify MCP para preguntas de 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.", "6. Prefiere los tests y puntos de entrada relevantes identificados por KlapContext."]
+    text="\n".join(lines).rstrip()+"\n"; return text+f"\nTokens estimados: {max(1, len(text.split()) * 4 // 3)}\n"
+def write(context: dict, output: Path) -> str:
+    text=render(context); output.write_text(text, encoding="utf-8"); return text

klapcontext-0.1.0/src/klapcontext/cli.py

@@ -0,0 +1,71 @@
+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 .context_builder import build
+from .git import commit, dirty_files, exclude_klap, is_repository
+from .graphify import GraphifyError, copy_outputs, generate, load_graph, version
+from .portal import write as write_portal
+
+def root_path(value: str | None) -> Path: return Path(value or os.getcwd()).resolve()
+
+def generate_all(root: Path, update: 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)
+    graph_path=generate(root, update); files=copy_outputs(root, klap/"graphify")
+    context=build(root, 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"); write_portal(context, agent, files, klap/"index.html")
+    state={"schema_version":"0.1","generated_at":datetime.now(timezone.utc).isoformat(),"git_commit":commit(root),"graphify_version":version(),"klap_version":__version__}
+    (klap/"state.json").write_text(json.dumps(state, indent=2)+"\n", encoding="utf-8")
+    return context
+
+def cmd_init(args):
+    root=root_path(args.path); print("KlapContext\n")
+    try:
+        context=generate_all(root)
+    except (RuntimeError, GraphifyError) as e:
+        print(f"✗ {e}", 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")
+    print(f"\nProject: {context['project']['name']}\nStack: {' / '.join(sum((v for v in context['stack'].values()), [])) 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):
+    try: generate_all(root_path(args.path), update=True)
+    except (RuntimeError, GraphifyError) as e: print(f"✗ {e}", file=sys.stderr); return 1
+    print("✓ KlapContext updated"); 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
+    state=json.loads(state_file.read_text(encoding="utf-8")); current=commit(root); dirty=dirty_files(root)
+    fresh=state.get("git_commit")==current and not dirty
+    print(f"Context commit: {(state.get('git_commit') or 'none')[:12]}\nCurrent commit: {(current or 'none')[:12]}\nUncommitted changes: {len(dirty)} files\n\nStatus: {'✓ CURRENT' if fresh else '⚠ STALE'}")
+    return 0 if fresh 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):
+    graph=root_path(args.path)/".klap"/"graphify"/"graph.json"
+    if not graph.exists(): print("⚠ No Graphify graph found. Run: klap init", file=sys.stderr); return 1
+    print("Graphify MCP (stdio):\npython -m graphify.serve " + str(graph) + "\n\nGeneric configuration:\n{\n  \"mcpServers\": {\n    \"graphify\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"graphify.serve\", \"" + str(graph).replace('\\','\\\\') + "\"]\n    }\n  }\n}")
+    return 0
+
+def main(argv=None):
+    # PowerShell's legacy cp1252 console otherwise raises on the intended status symbols.
+    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")):
+        p=subs.add_parser(name, help=help_text); p.add_argument("path", nargs="?", help="Repository root (defaults to current directory)"); p.set_defaults(func=func)
+    args=parser.parse_args(argv); return args.func(args)
+
+if __name__ == "__main__": raise SystemExit(main())

klapcontext-0.1.0/src/klapcontext/context_builder.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .detector import detect_project
+from .evidence import Evidence
+from .git import commit
+from .system import deployment, documents, entry_points, external_systems, purpose
+
+
+def _nodes(graph: dict) -> list[dict]:
+    return graph.get("nodes", []) if isinstance(graph.get("nodes"), list) else graph.get("graph", {}).get("nodes", [])
+
+
+def _modules(nodes: list[dict]) -> list[dict]:
+    result=[]
+    for node in nodes:
+        name=node.get("label") or node.get("name") or node.get("id"); path=node.get("file") or node.get("path")
+        if name and path:
+            kind=node.get("type", "module")
+            result.append({"name":name,"path":path,"kind":kind,"description":f"Contains {str(kind).lower()} code related to {name}.","status":"CONFIRMED","evidence":[Evidence("graphify",str(path),"Graphify node", "CONFIRMED",1.0).as_dict()]})
+    return result[:100]
+
+
+def _runtime(points: list[dict], background: list[dict], framework: list[str]) -> dict:
+    modes=[]; sentences=[]
+    if any(p["type"] == "http" for p in points): modes.append("http"); sentences.append("Las solicitudes HTTP ingresan a través de declaraciones de rutas detectadas.")
+    if any(p["type"] == "cli" for p in points): modes.append("cli"); sentences.append("El repositorio expone puntos de entrada ejecutables por línea de comandos.")
+    if background: modes.append("scheduler"); sentences.append("La aplicación declara procesos programados en segundo plano.")
+    if framework: sentences.append(f"La capa de framework detectada es {', '.join(framework)}.")
+    return {"modes":modes,"layers":[],"description":" ".join(sentences) if sentences else None,"status":"CONFIRMED" if sentences else "UNKNOWN"}
+
+
+def _io(points: list[dict], systems: list[dict], stores: list[dict]) -> tuple[list[dict], list[dict]]:
+    inputs=[]; outputs=[]
+    if any(p["type"]=="http" for p in points): inputs.append({"type":"http_request","description":"Solicitudes HTTP","status":"CONFIRMED"}) ; outputs.append({"type":"http_response","description":"Respuestas HTTP","status":"INFERRED"})
+    if any(p["type"]=="cli" for p in points): inputs.append({"type":"cli","description":"Invocación por línea de comandos","status":"CONFIRMED"})
+    if stores: inputs.append({"type":"datastore","description":"Lecturas o escrituras de base de datos","status":"INFERRED"}); outputs.append({"type":"datastore","description":"Escrituras de base de datos","status":"INFERRED"})
+    for system in systems:
+        if system["type"] == "http_api":
+            outputs.append({"type":"external_api","description":system["name"],"status":"CONFIRMED"})
+    return inputs, outputs
+
+
+def _flows(points: list[dict], modules: list[dict], systems: list[dict], stores: list[dict]) -> list[dict]:
+    flows=[]; targets=[m for m in modules if any(x in str(m["kind"]).lower() for x in ("controller","command","service"))]
+    for point in points:
+        if point["type"] not in {"http","scheduled"}: continue
+        steps=[{"name":point["name"],"kind":"trigger","path":point.get("path")}]
+        if point.get("target"): steps.append({"name":point["target"],"kind":"target","path":point.get("path")})
+        for module in targets[:2]:
+            if module["name"] != point.get("target"): steps.append({"name":module["name"],"kind":module["kind"],"path":module["path"]})
+        if stores: steps.append({"name":stores[0]["name"],"kind":"datastore","path":None})
+        elif systems: steps.append({"name":systems[0]["name"],"kind":"external_system","path":None})
+        if len(steps) > 1:
+            flows.append({"name":point["name"],"trigger":point["type"],"entry_point":point["name"],"steps":steps,"inputs":[],"outputs":[],"external_systems":[x["name"] for x in systems],"datastores":[x["name"] for x in stores],"tests":[],"status":"INFERRED","confidence":None,"evidence":point["evidence"]})
+    return flows[:3]
+
+
+def _important(root: Path, points: list[dict], deploy: dict, docs: list[dict]) -> list[dict]:
+    result=[]
+    for filename, role in (("pyproject.toml","Manifiesto de dependencias"),("package.json","Manifiesto de dependencias"),("composer.json","Manifiesto de dependencias"),("Dockerfile","Build de contenedor"),("docker-compose.yml","Topología de contenedores"),("README.md","Documentación del proyecto")):
+        if (root/filename).exists(): result.append({"path":filename,"role":role,"reason":f"{role} detected"})
+    for point in points:
+        if point["path"] not in {x["path"] for x in result}: result.append({"path":point["path"],"role":f"{point['type']} entry points","reason":"Contains detected entry point"})
+    return result[:20]
+
+
+def _start_here(points: list[dict], background: list[dict], modules: list[dict], systems: list[dict], important: list[dict]) -> list[dict]:
+    result=[]
+    http=[p for p in points if p["type"]=="http"]
+    if http: result.append({"intent":"Entender la API HTTP","paths":sorted({p["path"] for p in http}),"reason":"Contiene puntos de entrada HTTP confirmados"})
+    if background: result.append({"intent":"Entender procesos en segundo plano","paths":sorted({p["path"] for p in background}),"reason":"Contiene procesos programados"})
+    if systems: result.append({"intent":"Entender integraciones","paths":sorted({p for s in systems for p in s["configuration"]}),"reason":"Contiene configuración o uso de sistemas externos"})
+    manifests=[x["path"] for x in important if x["role"]=="Dependency manifest"]
+    if manifests: result.append({"intent":"Entender la configuración del proyecto","paths":manifests,"reason":"Manifiestos de dependencias"})
+    return result
+
+
+def _story(purpose_value: dict, runtime: dict, systems: list[dict], stores: list[dict], deploy: dict) -> dict:
+    sentences=[]
+    if purpose_value["text"]: sentences.append(purpose_value["text"].rstrip("." ) + ".")
+    if runtime["description"]: sentences.append(runtime["description"])
+    if systems: sentences.append("Los sistemas externos detectados incluyen " + ", ".join(x["name"] for x in systems) + ".")
+    if stores: sentences.append("Los almacenes de datos detectados incluyen " + ", ".join(x["name"] for x in stores) + ".")
+    if "Docker" in deploy["tools"]: sentences.append("La aplicación está contenerizada con Docker.")
+    return {"text":" ".join(sentences) if sentences else None,"status":"CONFIRMED" if sentences else "UNKNOWN"}
+
+
+def build(root: Path, graph: dict) -> dict:
+    stack, stack_evidence=detect_project(root); docs=documents(root); purpose_value=purpose(root, docs)
+    points, background=entry_points(root); systems, stores=external_systems(root); deploy, observability, _=deployment(root)
+    modules=_modules(_nodes(graph)); runtime=_runtime(points, background, stack["frameworks"]); inputs, outputs=_io(points, systems, stores)
+    flows=_flows(points, modules, systems, stores); important=_important(root, points, deploy, docs); start=_start_here(points, background, modules, systems, important)
+    architecture={"style":None,"status":"UNKNOWN","confidence":None,"evidence":[]}
+    if "Laravel" in stack["frameworks"]: architecture={"style":"MVC","status":"INFERRED","confidence":None,"evidence":[Evidence("file","composer.json","Laravel convention suggests MVC","INFERRED",.8).as_dict()]}
+    tests=[{"path":path,"reason":"Test configuration or directory detected"} for path in ("tests","test","phpunit.xml","pytest.ini") if (root/path).exists()]
+    name=root.name
+    technical={"languages":stack["languages"],"frameworks":stack["frameworks"],"dependencies":[],"graph":{"nodes":len(_nodes(graph)),"edges":len(graph.get("edges", graph.get("graph",{}).get("edges",[])))},"documents":[{"path":d["path"]} for d in docs],"tests":tests,"infrastructure":stack["infrastructure"]}
+    system={"purpose":purpose_value,"project_story":_story(purpose_value,runtime,systems,stores,deploy),"runtime":runtime,"entry_points":points,"main_flows":flows,"capabilities":modules,"inputs":inputs,"outputs":outputs,"external_systems":systems,"background_processes":background,"datastores":stores,"deployment":deploy,"observability":observability,"important_files":important,"start_here":start,"unknowns":[label for label,value in (("Propósito de negocio del proyecto",purpose_value["text"]),("Modelo de ejecución",runtime["description"]),("Plataforma de despliegue en producción",deploy["tools"])) if not value]}
+    project={"name":name,"type":stack["frameworks"][0] if stack["frameworks"] else None,"root":str(root.resolve()),"generated_at":datetime.now(timezone.utc).isoformat(),"git_commit":commit(root)}
+    # Keep v0.1 top-level fields for consumers while promoting the separated model.
+    return {"schema_version":"0.2","project":project,"technical_model":technical,"system_model":system,"human_context":{"purpose":None,"users":None,"important_processes":[],"notes":[]},"stack":stack,"architecture":architecture,"entry_points":points,"modules":modules,"flows":flows,"api":[],"jobs":background,"datastores":stores,"external_systems":systems,"deployment":deploy,"observability":observability,"tests":tests,"evidence":[x.as_dict() for x in stack_evidence]+purpose_value["evidence"]}

klapcontext-0.1.0/src/klapcontext/detector.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .evidence import Evidence
+
+
+def detect_project(root: Path) -> tuple[dict, list[Evidence]]:
+    evidence: list[Evidence] = []
+    stack = {"languages": [], "frameworks": [], "databases": [], "runtime": [], "infrastructure": []}
+    def add(bucket: str, value: str, path: str, reason: str) -> None:
+        if value not in stack[bucket]: stack[bucket].append(value)
+        evidence.append(Evidence("file", path, reason, "CONFIRMED", 1.0))
+    composer = root / "composer.json"
+    if composer.exists():
+        add("languages", "PHP", "composer.json", "Composer manifest detected")
+        try: deps = {**json.loads(composer.read_text(encoding="utf-8")).get("require", {}), **json.loads(composer.read_text(encoding="utf-8")).get("require-dev", {})}
+        except json.JSONDecodeError: deps = {}
+        if "laravel/framework" in deps: add("frameworks", "Laravel", "composer.json", "laravel/framework dependency detected")
+    package = root / "package.json"
+    if package.exists():
+        add("languages", "JavaScript", "package.json", "npm manifest detected")
+        try: deps = {**json.loads(package.read_text(encoding="utf-8")).get("dependencies", {}), **json.loads(package.read_text(encoding="utf-8")).get("devDependencies", {})}
+        except json.JSONDecodeError: deps = {}
+        for name, label in (("next", "Next.js"), ("vue", "Vue"), ("react", "React"), ("express", "Express")):
+            if name in deps: add("frameworks", label, "package.json", f"{name} dependency detected")
+    if (root / "pyproject.toml").exists() or (root / "requirements.txt").exists(): add("languages", "Python", "pyproject.toml" if (root / "pyproject.toml").exists() else "requirements.txt", "Python manifest detected")
+    if (root / "manage.py").exists(): add("frameworks", "Django", "manage.py", "Django entry point detected")
+    if list(root.glob("*.csproj")): add("languages", "C#", next(root.glob("*.csproj")).name, ".NET project detected")
+    if (root / "Dockerfile").exists(): add("infrastructure", "Docker", "Dockerfile", "Dockerfile detected")
+    if list(root.glob("docker-compose*")) or list(root.glob("compose*")): add("infrastructure", "Docker Compose", "docker-compose", "Compose configuration detected")
+    if (root / ".github" / "workflows").exists(): add("infrastructure", "GitHub Actions", ".github/workflows", "GitHub Actions workflows detected")
+    return stack, evidence

klapcontext-0.1.0/src/klapcontext/evidence.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+from dataclasses import asdict, dataclass
+
+@dataclass(frozen=True)
+class Evidence:
+    source_type: str
+    path: str
+    reason: str
+    status: str = "CONFIRMED"
+    confidence: float = 1.0
+    def as_dict(self): return asdict(self)

klapcontext-0.1.0/src/klapcontext/git.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def run_git(root: Path, *args: str) -> str | None:
+    result = subprocess.run(["git", *args], cwd=root, text=True, capture_output=True)
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def is_repository(root: Path) -> bool:
+    return run_git(root, "rev-parse", "--is-inside-work-tree") == "true"
+
+
+def commit(root: Path) -> str | None:
+    return run_git(root, "rev-parse", "HEAD")
+
+
+def dirty_files(root: Path) -> list[str]:
+    output = run_git(root, "status", "--porcelain") or ""
+    return [line[3:] for line in output.splitlines() if line]
+
+
+def exclude_klap(root: Path) -> None:
+    git_dir = run_git(root, "rev-parse", "--git-dir")
+    if not git_dir:
+        raise RuntimeError("Not a Git repository")
+    exclude = (root / git_dir / "info" / "exclude").resolve()
+    exclude.parent.mkdir(parents=True, exist_ok=True)
+    existing = exclude.read_text(encoding="utf-8") if exclude.exists() else ""
+    additions = [entry for entry in (".klap/", "graphify-out/") if entry not in {line.strip() for line in existing.splitlines()}]
+    if additions:
+        exclude.write_text(existing.rstrip() + ("\n" if existing.strip() else "") + "\n".join(additions) + "\n", encoding="utf-8")

klapcontext-0.1.0/src/klapcontext/graphify.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+import importlib.metadata, json, shutil, subprocess, sys
+from pathlib import Path
+
+class GraphifyError(RuntimeError): pass
+
+def executable() -> str | None: return shutil.which("graphify")
+
+def command_prefix() -> list[str] | None:
+    """Use the console script when present; PyPI's current package also supports python -m graphify."""
+    if executable(): return [executable()]
+    try:
+        import graphify  # noqa: F401
+        return [sys.executable, "-m", "graphify"]
+    except ImportError: return None
+
+def version() -> str | None:
+    try: return importlib.metadata.version("graphifyy")
+    except importlib.metadata.PackageNotFoundError: return None
+
+def generate(root: Path, update: bool = False) -> Path:
+    prefix = command_prefix()
+    if not prefix: raise GraphifyError("Graphify is required. Install it with: pipx install graphifyy")
+    # Graphify owns parsing/incrementality; --code-only keeps KlapContext's base fully local/no-LLM.
+    command = prefix + (["update", str(root)] if update else ["extract", str(root), "--code-only"])
+    result = subprocess.run(command, cwd=root, text=True, capture_output=True)
+    # Some current Windows Graphify builds can abort in `update`; retain its
+    # incremental fast path but recover with the documented deterministic scan.
+    if update and result.returncode != 0:
+        result = subprocess.run(prefix + ["extract", str(root), "--code-only"], cwd=root, text=True, capture_output=True)
+    graph = root / "graphify-out" / "graph.json"
+    if result.returncode != 0 or not graph.exists():
+        message = result.stderr.strip() or result.stdout.strip() or "Graphify did not create graph.json"
+        raise GraphifyError(message)
+    # Visualization exporters are Graphify's implementation, not a KlapContext reimplementation.
+    for export in (["export", "html", "--graph", str(graph)], ["export", "callflow-html", str(graph)]):
+        subprocess.run(prefix + export, cwd=root, text=True, capture_output=True)
+    return graph
+
+def load_graph(graph: Path) -> dict:
+    try: return json.loads(graph.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError): return {}
+
+def copy_outputs(root: Path, destination: Path) -> list[str]:
+    import shutil
+    source = root / "graphify-out"; destination.mkdir(parents=True, exist_ok=True); copied=[]
+    for name in ("graph.json", "graph.html", "GRAPH_REPORT.md"):
+        if (source/name).exists(): shutil.copy2(source/name, destination/name); copied.append(name)
+    callflows = list(source.glob("*-callflow.html")) + list(source.glob("callflow.html"))
+    if callflows:
+        shutil.copy2(callflows[0], destination/"callflow.html"); copied.append("callflow.html")
+    return copied

klapcontext-0.1.0/src/klapcontext/portal.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import html, json
+from pathlib import Path
+
+def e(x): return html.escape(str(x))
+def rows(items, key="name"):
+    return "".join(f"<li><i></i><code>{e(x.get(key) or x.get('path'))}</code><small>{e(x.get('type') or x.get('role') or '')}</small></li>" for x in items)
+def panel(title, content, tone=""):
+    return f"<section class='panel {tone}'><header><h2>{title}</h2></header>{content}</section>" if content else ""
+
+def render(context: dict, agent_text: str, graphify_files: list[str]) -> str:
+    p=context["project"]; s=context.get("system_model", {}); stack=[v for values in context["stack"].values() for v in values]
+    purpose=s.get("purpose",{}).get("text") or "No fue posible determinar el propósito del proyecto con confianza."
+    story=s.get("project_story",{}).get("text") or s.get("runtime",{}).get("description") or "No fue posible determinar cómo funciona el sistema con confianza."
+    points=s.get("entry_points",[]); flows=s.get("main_flows",[]); unknowns=s.get("unknowns",[])
+    tags="".join(f"<span>{e(x)}</span>" for x in stack) or "<span>Stack desconocido</span>"
+    flow_html="".join(f"<article class='flow'><b>{e(x['name'])}</b><p>{' <em>→</em> '.join(e(step['name']) for step in x['steps'])}</p></article>" for x in flows) or "<p class='empty'>No se detectaron flujos principales con confianza.</p>"
+    start="".join(f"<li><b>{e(x['intent'])}</b><span>{e(' · '.join(x['paths']))}</span></li>" for x in s.get("start_here",[])) or "<li class='empty'>No se detectaron recomendaciones de onboarding.</li>"
+    evidence="".join(f"<li><i></i><div><code>{e(x['path'])}</code><p>{e(x['reason'])}</p></div><b>{e(x['status'])}</b></li>" for x in context.get("evidence",[]))
+    exploration="".join(f"<a href='graphify/{name}'>{label}<b>↗</b></a>" for name,label in (("graph.html","Abrir grafo técnico"),("callflow.html","Abrir call flows"),("GRAPH_REPORT.md","Abrir informe técnico")) if name in graphify_files)
+    body=[panel("Qué es este proyecto",f"<p class='purpose'>{e(purpose)}</p><p class='story'>{e(story)}</p>","intro"),panel("Flujos principales",f"<div class='flows'>{flow_html}</div>"),panel("Puntos de entrada",f"<ul class='list'>{rows(points)}</ul>" if points else "<p class='empty'>No se detectaron puntos de entrada.</p>"),panel("Capacidades",f"<ul class='list'>{rows(s.get('capabilities',[]))}</ul>" if s.get('capabilities') else ""),panel("Entradas y salidas",f"<div class='duo'><div><label>ENTRADAS</label><ul class='list'>{rows(s.get('inputs',[]),'description')}</ul></div><div><label>SALIDAS</label><ul class='list'>{rows(s.get('outputs',[]),'description')}</ul></div></div>" if s.get('inputs') or s.get('outputs') else ""),panel("Sistemas externos",f"<ul class='list'>{rows(s.get('external_systems',[]))}</ul>" if s.get('external_systems') else ""),panel("Procesos en segundo plano",f"<ul class='list'>{rows(s.get('background_processes',[]))}</ul>" if s.get('background_processes') else ""),panel("Despliegue",f"<ul class='list'>{rows(s.get('deployment',{}).get('files',[]),'path')}</ul>" if s.get('deployment',{}).get('files') else ""),panel("Por dónde empezar",f"<ul class='start'>{start}</ul>"),panel("Lo que no pudimos determinar","<ul class='list'>"+"".join(f"<li><i></i><code>{e(x)}</code></li>" for x in unknowns)+"</ul>" if unknowns else ""),panel("Evidencia",f"<ul class='evidence'>{evidence}</ul>" if evidence else ""),panel("Exploración técnica",f"<div class='links'>{exploration}</div>" if exploration else "")]
+    agent=json.dumps(agent_text).replace("</","<\\/")
+    return f"""<!doctype html><html lang='es'><meta charset='utf-8'><meta name='viewport' content='width=device-width,initial-scale=1'><title>KlapContext · {e(p['name'])}</title><style>
+@import url('https://fonts.googleapis.com/css2?family=DM+Mono:wght@400;500&family=Manrope:wght@400;500;600;700;800&display=swap');:root{{--bg:#080d19;--bar:#10182b;--card:#111b30;--line:#20324e;--ink:#edf4ff;--muted:#8596b4;--cyan:#16dbc3;--violet:#8476ff;--amber:#ffb84c}}*{{box-sizing:border-box}}body{{margin:0;background:var(--bg);color:var(--ink);font:14px/1.55 Manrope,sans-serif;background-image:linear-gradient(#ffffff07 1px,transparent 1px),linear-gradient(90deg,#ffffff07 1px,transparent 1px);background-size:32px 32px}}.top{{height:58px;display:flex;align-items:center;gap:15px;padding:0 22px;border-bottom:1px solid var(--line);background:#0b1222ee;position:sticky;top:0;z-index:5}}.logo{{display:flex;gap:8px;align-items:center;font-weight:800;letter-spacing:.08em;font-size:12px}}.logo b{{display:grid;place-items:center;width:26px;height:26px;border-radius:7px;background:linear-gradient(135deg,var(--cyan),var(--violet));color:#081323}}.repo{{padding:6px 10px;border-radius:5px;background:#141f36;color:#ced9f1;font:11px 'DM Mono'}}.top .state{{margin-left:auto;color:var(--cyan);font:10px 'DM Mono'}}.top button{{border:1px solid #35d7c780;border-radius:6px;background:#12bfae;color:#041a1c;padding:7px 10px;font:700 11px Manrope;cursor:pointer}}.app{{max-width:1440px;margin:auto;display:grid;grid-template-columns:210px minmax(0,1fr) 290px;min-height:calc(100vh - 58px)}}.side{{padding:18px 14px;border-right:1px solid var(--line);background:#0a1120cc}}.score{{padding:15px;border:1px solid var(--line);border-left:3px solid var(--cyan);border-radius:8px;background:var(--bar)}}.score b{{display:block;font-size:25px;letter-spacing:-.07em}}.score span{{color:var(--muted);font:10px 'DM Mono'}}.side h3{{margin:25px 8px 8px;color:var(--cyan);font:10px 'DM Mono';letter-spacing:.12em}}.side a{{display:block;padding:7px 8px;color:var(--muted);font-size:12px;text-decoration:none;border-radius:5px}}.side a:hover{{color:var(--ink);background:#182440}}main{{padding:20px;min-width:0}}.hero{{padding:27px 29px;border:1px solid var(--line);border-radius:11px;background:linear-gradient(120deg,#17264a,#111a30);position:relative;overflow:hidden}}.hero:after{{content:'';position:absolute;right:-80px;top:-115px;width:280px;height:280px;border:1px solid #16dbc344;border-radius:50%;box-shadow:0 0 0 35px #16dbc308,0 0 0 70px #8476ff08}}.eyebrow,label{{color:var(--cyan);font:10px 'DM Mono';letter-spacing:.13em}}h1{{position:relative;margin:7px 0;font-size:clamp(30px,4vw,47px);letter-spacing:-.06em;line-height:1.05}}.hero p{{position:relative;margin:0;color:#b8c6e0;max-width:650px}}.tags{{position:relative;margin-top:18px;display:flex;gap:7px;flex-wrap:wrap}}.tags span{{font:10px 'DM Mono';padding:4px 7px;border:1px solid #476189;border-radius:4px}}.stats{{display:grid;grid-template-columns:repeat(3,1fr);gap:9px;margin:13px 0}}.stat{{padding:11px;border:1px solid var(--line);border-radius:7px;background:#0c1527}}.stat b{{display:block;font-size:20px}}.stat span{{font-size:10px;color:var(--muted)}}.panels{{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}}.panel{{padding:18px;border:1px solid var(--line);border-radius:9px;background:#101a2edb}}.panel.intro,.panel:nth-last-child(-n+3){{grid-column:1/-1}}header{{display:flex;justify-content:space-between;margin-bottom:11px}}h2{{margin:0;font-size:14px}}.purpose{{margin:0;color:#e4ecfa;font-size:16px}}.story{{margin:9px 0 0;color:var(--muted)}}.list,.evidence,.start{{list-style:none;margin:0;padding:0}}.list li{{display:grid;grid-template-columns:8px 1fr auto;align-items:center;gap:7px;padding:7px 0;border-bottom:1px solid #20304a}}.list li:last-child{{border:0}}i{{display:block;width:5px;height:5px;border-radius:50%;background:var(--violet);box-shadow:0 0 8px var(--violet)}}code{{font:11px 'DM Mono';color:#d9e5ff;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}}small{{font:10px 'DM Mono';color:var(--muted)}}.empty{{color:var(--muted);font-size:12px}}.flows{{display:grid;gap:8px}}.flow{{padding:11px;border:1px solid #28425d;border-radius:6px;background:#091323}}.flow b{{font-size:12px}}.flow p{{margin:5px 0 0;font:11px/1.75 'DM Mono';color:#c8d6f1}}.flow em{{color:var(--cyan);font-style:normal}}.duo{{display:grid;grid-template-columns:1fr 1fr;gap:18px}}.start li{{padding:8px 0;border-bottom:1px solid var(--line)}}.start b{{display:block;font-size:12px}}.start span{{color:var(--muted);font:10px 'DM Mono'}}.evidence li{{display:flex;gap:8px;padding:8px 0;border-bottom:1px solid var(--line)}}.evidence p{{margin:1px 0;color:var(--muted);font-size:10px}}.evidence li>b{{margin-left:auto;color:var(--cyan);font:10px 'DM Mono'}}.links{{display:flex;gap:8px;flex-wrap:wrap}}.links a{{border:1px solid #2f5d7c;border-radius:5px;padding:8px 10px;text-decoration:none;font:11px 'DM Mono';background:#0b1426}}.links a:hover{{border-color:var(--cyan)}}.right{{padding:20px 14px;border-left:1px solid var(--line);background:#0a1120cc}}.right h3{{font-size:12px;margin:0 0 11px}}.callout{{padding:14px;border:1px solid #6859bb;border-radius:8px;background:linear-gradient(145deg,#28205a,#101b33)}}.callout p{{color:#bac6e0;font-size:12px}}.callout button{{width:100%;border:0;border-radius:5px;padding:9px;background:var(--cyan);font-weight:800;cursor:pointer}}.right .note{{margin-top:14px;padding:12px;border-left:2px solid var(--amber);background:#171827;color:var(--muted);font-size:11px}}@media(max-width:1000px){{.app{{grid-template-columns:185px 1fr}}.right{{display:none}}}}@media(max-width:680px){{.app{{display:block}}.side{{display:none}}main{{padding:12px}}.panels,.duo{{grid-template-columns:1fr}}.panel{{grid-column:auto!important}}.top .repo{{display:none}}.hero{{padding:23px}}}}
+</style><body><nav class='top'><div class='logo'><b>K</b>KLAPCONTEXT</div><span class='repo'>{e(p['name'])}</span><span class='state'>● {'ACTUAL' if p.get('git_commit') else 'SIN COMMIT'}</span><button onclick='copyContext(this)'>Copiar contexto</button></nav><div class='app'><aside class='side'><div class='score'><b>{len(points)}<small> / {len(context.get('evidence',[]))}</small></b><span>PUNTOS / EVIDENCIAS</span></div><h3>NAVEGACIÓN</h3><a href='#sistema'>Sistema</a><a href='#flujos'>Flujos</a><a href='#entradas'>Entradas</a><a href='#evidencia'>Evidencia</a><a href='#tecnico'>Graphify</a></aside><main><section class='hero'><div class='eyebrow'>COMPRENDER EL SISTEMA</div><h1>{e(p['name'])}</h1><p>Un mapa de ingeniería basado en evidencia para personas y agentes de IA.</p><div class='tags'>{tags}</div></section><div class='stats'><div class='stat'><b>{len(points)}</b><span>puntos de entrada</span></div><div class='stat'><b>{len(flows)}</b><span>flujos principales</span></div><div class='stat'><b>{len(context.get('evidence',[]))}</b><span>hechos confirmados</span></div></div><div class='panels'>{''.join(body)}</div></main><aside class='right'><h3>CONTEXTO PARA AGENTE</h3><section class='callout'><strong>Llevate el mapa</strong><p>Un briefing compacto con propósito, flujos, entry points e incertidumbres.</p><button onclick='copyContext(this)'>Copiar contexto</button></section><div class='note'>KlapContext distingue hechos confirmados de inferencias. Si no hay evidencia, lo indica explícitamente.</div></aside></div><script>const agentContext={agent};function copyContext(b){{navigator.clipboard.writeText(agentContext).then(()=>{{const old=b.textContent;b.textContent='Copiado';setTimeout(()=>b.textContent=old,1500)}})}}</script></body></html>"""
+def write(context: dict, agent_text: str, graphify_files: list[str], output: Path) -> None: output.write_text(render(context,agent_text,graphify_files),encoding='utf-8')

klapcontext-0.1.0/src/klapcontext/system.py

@@ -0,0 +1,123 @@
+"""Deterministic system-understanding heuristics, all backed by repository evidence."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .evidence import Evidence
+
+
+TEXT_LIMIT = 180_000
+
+
+def _read(path: Path) -> str:
+    try: return path.read_text(encoding="utf-8", errors="replace")[:TEXT_LIMIT]
+    except OSError: return ""
+
+
+def _ev(path: str, reason: str, status: str = "CONFIRMED", confidence: float = 1.0) -> dict:
+    return Evidence("file", path, reason, status, confidence).as_dict()
+
+
+def documents(root: Path) -> list[dict]:
+    candidates = [*root.glob("README*"), *root.glob("CONTRIBUTING*"), *root.glob("Makefile")]
+    for folder in ("docs", "doc", "ADR", "architecture"):
+        directory = root / folder
+        if directory.is_dir(): candidates.extend(p for p in directory.rglob("*.md") if p.is_file())
+    seen, result = set(), []
+    for path in candidates:
+        relative = str(path.relative_to(root))
+        if relative in seen or path.stat().st_size > TEXT_LIMIT: continue
+        seen.add(relative)
+        result.append({"path": relative, "content": _read(path)})
+    return result
+
+
+def purpose(root: Path, docs: list[dict]) -> dict:
+    def localize(text: str) -> str:
+        # Product metadata can be English even when this local context is emitted in Spanish.
+        return "Hace que tu repositorio sea comprensible para humanos e IA." if text.strip() == "Make your repository understandable to humans and AI." else text
+    package = root / "package.json"; pyproject = root / "pyproject.toml"
+    if package.exists():
+        try:
+            description = json.loads(_read(package)).get("description")
+            if description: return {"text": localize(description), "status": "CONFIRMED", "evidence": [_ev("package.json", "Package description")]} 
+        except json.JSONDecodeError: pass
+    if pyproject.exists():
+        match = re.search(r'^description\s*=\s*["\'](.+?)["\']', _read(pyproject), re.M)
+        if match: return {"text": localize(match.group(1)), "status": "CONFIRMED", "evidence": [_ev("pyproject.toml", "Project description")]} 
+    for doc in docs:
+        if Path(doc["path"]).name.lower().startswith("readme"):
+            paragraphs = [re.sub(r"\s+", " ", p).strip() for p in re.split(r"\n\s*\n", doc["content"])]
+            for paragraph in paragraphs:
+                if paragraph and not paragraph.startswith("#") and len(paragraph) >= 30 and not paragraph.startswith("```"):
+                    return {"text": paragraph[:400], "status": "CONFIRMED", "evidence": [_ev(doc["path"], "README project description")]} 
+    return {"text": None, "status": "UNKNOWN", "evidence": []}
+
+
+def entry_points(root: Path) -> tuple[list[dict], list[dict]]:
+    points, background = [], []
+    def add(kind, name, path, target=None, schedule=None, reason="Application entry point detected"):
+        evidence=[_ev(path, reason)]
+        point={"type":kind,"name":name,"path":path,"target":target,"schedule":schedule,"status":"CONFIRMED","evidence":evidence}
+        points.append(point); return point
+    # Laravel routes and scheduler.
+    for route_file in (root / "routes").glob("*.php") if (root / "routes").is_dir() else []:
+        text=_read(route_file); rel=str(route_file.relative_to(root))
+        for method, uri, target in re.findall(r"Route::(get|post|put|patch|delete|any)\s*\(\s*['\"]([^'\"]+)['\"]\s*,\s*([^\)]+)", text, re.I):
+            add("http", f"{method.upper()} /{uri.lstrip('/')}", rel, target.strip(), reason="Laravel route declaration")
+    for rel in ("routes/console.php", "app/Console/Kernel.php"):
+        if not (root/rel).exists(): continue
+        text=_read(root/rel)
+        for command, frequency in re.findall(r"(?:command|job)\s*\(\s*['\"]([^'\"]+)['\"]\s*\).*?->(every\w+|daily|hourly|weekly)\s*\(", text, re.S):
+            point=add("scheduled", command, rel, schedule=frequency, reason="Laravel scheduler declaration")
+            background.append({"name":command,"type":"scheduled_command","schedule":frequency,"path":rel,"status":"CONFIRMED","evidence":point["evidence"]})
+    # Python HTTP decorators and CLI bootstrap.
+    for path in root.rglob("*.py"):
+        if any(part in {".git", ".klap", "graphify-out", "venv", ".venv"} for part in path.parts) or path.name == "system.py": continue
+        text=_read(path); rel=str(path.relative_to(root))
+        for method, uri, function in re.findall(r"@\w+\.(get|post|put|patch|delete)\s*\(\s*['\"]([^'\"]+)['\"]\s*\)\s*\n\s*(?:async\s+)?def\s+(\w+)", text, re.I):
+            add("http", f"{method.upper()} {uri}", rel, function, reason="Python web route decorator")
+        if "if __name__ == \"__main__\"" in text or "if __name__ == '__main__'" in text:
+            add("cli", path.stem, rel, reason="Python executable module")
+    # Express route declarations.
+    for path in root.rglob("*.js"):
+        if any(part in {"node_modules", ".git", ".klap", "graphify-out"} for part in path.parts): continue
+        rel=str(path.relative_to(root)); text=_read(path)
+        for method, uri in re.findall(r"\.(get|post|put|patch|delete)\s*\(\s*['\"]([^'\"]+)", text, re.I): add("http", f"{method.upper()} {uri}", rel, reason="JavaScript HTTP route declaration")
+    return points[:50], background[:30]
+
+
+def external_systems(root: Path) -> tuple[list[dict], list[dict]]:
+    found, stores = [], []
+    patterns = [(r"\bredis\b", "Redis", "redis"), (r"\brabbitmq\b|\bamqp\b", "RabbitMQ", "message broker"), (r"\bkafka\b", "Kafka", "message broker"), (r"\bsentry\b", "Sentry", "error tracking"), (r"\bsmtp\b|\bmailgun\b", "SMTP", "email"), (r"\bsftp\b", "SFTP", "sftp"), (r"\bftp\b", "FTP", "ftp")]
+    store_patterns = [(r"\bmysql\b", "MySQL"), (r"\bpostgres(?:ql)?\b", "PostgreSQL"), (r"\bsqlsrv\b|sql server", "SQL Server"), (r"\bsqlite\b", "SQLite"), (r"\bmongodb\b", "MongoDB")]
+    candidates=[p for p in root.rglob("*") if p.is_file() and p.suffix.lower() in {".json", ".toml", ".yml", ".yaml", ".php", ".py", ".js", ".ts", ".env"}]
+    for path in candidates[:800]:
+        if any(part in {".git", ".klap", "graphify-out", "node_modules", "vendor", ".pytest_cache", "tests"} for part in path.parts) or path.name in {"system.py", "portal.py"}: continue
+        text=_read(path); rel=str(path.relative_to(root))
+        for pattern,name,kind in patterns:
+            if re.search(pattern, text, re.I) and not any(x["name"] == name for x in found): found.append({"name":name,"type":kind,"purpose":None,"used_by":[],"configuration":[rel],"status":"CONFIRMED","evidence":[_ev(rel, f"{name} configuration or usage detected")]})
+        for pattern,name in store_patterns:
+            if re.search(pattern, text, re.I) and not any(x["name"] == name for x in stores): stores.append({"name":name,"connection":None,"used_by":[],"role":None,"status":"CONFIRMED","evidence":[_ev(rel, f"{name} configuration or usage detected")]})
+        for host in re.findall(r"https?://([a-zA-Z0-9.-]+)", text):
+            if host not in {"localhost", "example.com"} and not any(x["name"] == host for x in found): found.append({"name":host,"type":"http_api","purpose":None,"used_by":[],"configuration":[rel],"status":"CONFIRMED","evidence":[_ev(rel, "External HTTP host configured or referenced")]})
+    return found, stores
+
+
+def deployment(root: Path) -> tuple[dict, dict, list[dict]]:
+    files=[]; tools=[]; ports=[]; observability=[]
+    for name, label in (("Dockerfile","Docker"),("docker-compose.yml","Docker Compose"),("docker-compose.yaml","Docker Compose"),("compose.yml","Docker Compose"),("compose.yaml","Docker Compose"),("Jenkinsfile","Jenkins")):
+        if (root/name).exists(): files.append({"path":name,"role":label,"reason":f"{label} configuration"}); tools.append(label)
+    if (root/".github/workflows").is_dir(): files.append({"path":".github/workflows","role":"CI workflows","reason":"GitHub Actions workflow directory"}); tools.append("GitHub Actions")
+    for item in files:
+        text=_read(root/item["path"]) if (root/item["path"]).is_file() else ""
+        ports.extend(re.findall(r"(?:EXPOSE\s+|['\"]?)(\d{2,5})(?::\d{2,5})?", text))
+    for path in root.rglob("*"):
+        if path.is_file() and path.suffix.lower() in {".py", ".php", ".js", ".ts", ".json", ".yml", ".yaml"}:
+            if any(part in {".git", ".klap", "graphify-out", "node_modules", "vendor", ".pytest_cache", "tests"} for part in path.parts) or path.name == "system.py": continue
+            text=_read(path); rel=str(path.relative_to(root))
+            for term,name in (("prometheus","Prometheus"),("opentelemetry","OpenTelemetry"),("sentry","Sentry"),("/health","Health endpoint"),("/metrics","Metrics endpoint")):
+                if term in text.lower() and not any(x["name"]==name for x in observability): observability.append({"name":name,"path":rel,"status":"CONFIRMED","evidence":[_ev(rel, f"{name} reference detected")]})
+    return {"tools":tools,"ports":sorted(set(ports)),"files":files,"status":"CONFIRMED" if files else "UNKNOWN"}, {"tools":observability,"status":"CONFIRMED" if observability else "UNKNOWN"}, files

klapcontext-0.1.0/src/klapcontext.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: klapcontext
+Version: 0.1.0
+Summary: Make your repository understandable to humans and AI.
+Author: Willy Cordon
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/willy-cordon/klap_context
+Project-URL: Repository, https://github.com/willy-cordon/klap_context
+Project-URL: Issues, https://github.com/willy-cordon/klap_context/issues
+Keywords: codebase,developer-tools,engineering-context,graphify,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphifyy>=0.9.66
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# KlapContext
+
+Make your repository understandable to humans and AI.
+
+KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
+portal estático para personas y un briefing compacto para agentes de IA. Usa
+[Graphify](https://github.com/Graphify-Labs/graphify) como motor local de
+análisis técnico; KlapContext no reimplementa su grafo ni sus parsers.
+
+```text
+Repositorio → KlapContext → Contexto de ingeniería
+                              ├── Portal humano
+                              └── Contexto para agentes
+```
+
+## Instalación
+
+```bash
+pip install klapcontext
+```
+
+La instalación incluye `graphifyy`, la distribución oficial de Graphify que
+KlapContext necesita para generar el análisis local. Como alternativa para una
+CLI aislada: `pipx install klapcontext`.
+
+## Primer uso
+
+```bash
+cd mi-proyecto
+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`.
+
+## Comandos
+
+| Comando | Descripción |
+| --- | --- |
+| `klap init [ruta]` | Genera el contexto inicial. |
+| `klap update [ruta]` | Actualiza Graphify y el contexto. |
+| `klap status [ruta]` | Indica si el contexto está actualizado respecto a Git. |
+| `klap open [ruta]` | Abre el portal humano estático. |
+| `klap agent [ruta]` | Muestra la configuración MCP local de Graphify. |
+| `klap --version` | Muestra la versión instalada. |
+
+## Salidas
+
+```text
+.klap/
+├── context.json          # modelo técnico, de sistema y humano
+├── agent-context.md      # briefing para agentes de IA
+├── index.html            # portal humano, sin servidor
+├── state.json            # metadatos de freshness
+└── graphify/             # grafo, informe y visualizaciones de Graphify
+```
+
+Las afirmaciones incluyen evidencia y estados `CONFIRMED`, `INFERRED` o
+`UNKNOWN`. Si KlapContext no puede determinar algo con confianza, lo expone en
+lugar de inventarlo.
+
+## Desarrollo
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Publicación
+
+El workflow de GitHub Actions publica tags `v*` mediante PyPI Trusted
+Publishing. Antes del primer tag, configurá el publisher de PyPI para este
+repositorio y workflow. No se necesitan tokens de PyPI en el repositorio.
+
+## Licencia
+
+Apache-2.0. Ver [LICENSE](LICENSE).

klapcontext-0.1.0/src/klapcontext.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/klapcontext/__init__.py
+src/klapcontext/agent_context.py
+src/klapcontext/cli.py
+src/klapcontext/context_builder.py
+src/klapcontext/detector.py
+src/klapcontext/evidence.py
+src/klapcontext/git.py
+src/klapcontext/graphify.py
+src/klapcontext/portal.py
+src/klapcontext/system.py
+src/klapcontext.egg-info/PKG-INFO
+src/klapcontext.egg-info/SOURCES.txt
+src/klapcontext.egg-info/dependency_links.txt
+src/klapcontext.egg-info/entry_points.txt
+src/klapcontext.egg-info/requires.txt
+src/klapcontext.egg-info/top_level.txt
+tests/test_klapcontext.py

klapcontext-0.1.0/src/klapcontext.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

klapcontext-0.1.0/src/klapcontext.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+klap = klapcontext.cli:main

klapcontext-0.1.0/src/klapcontext.egg-info/requires.txt

@@ -0,0 +1,6 @@
+graphifyy>=0.9.66
+
+[dev]
+build>=1.2
+pytest>=8
+twine>=6

klapcontext-0.1.0/src/klapcontext.egg-info/top_level.txt

@@ -0,0 +1 @@
+klapcontext

klapcontext-0.1.0/tests/test_klapcontext.py

@@ -0,0 +1,53 @@
+import json
+from pathlib import Path
+from klapcontext.agent_context import render as render_agent
+from klapcontext.context_builder import build
+from klapcontext.detector import detect_project
+from klapcontext.git import exclude_klap
+from klapcontext.portal import render as render_portal
+from klapcontext import cli
+
+def fixture_repo(tmp_path):
+    (tmp_path/".git"/"info").mkdir(parents=True)
+    (tmp_path/"composer.json").write_text(json.dumps({"require":{"laravel/framework":"^11.0"}}))
+    (tmp_path/"Dockerfile").write_text("FROM php:8.3")
+    (tmp_path/"routes").mkdir(); (tmp_path/"routes"/"api.php").write_text("<?php")
+    (tmp_path/"tests").mkdir()
+    return tmp_path
+
+def test_detector_collects_confirmed_evidence(tmp_path):
+    root=fixture_repo(tmp_path); stack, evidence=detect_project(root)
+    assert "Laravel" in stack["frameworks"] and "Docker" in stack["infrastructure"]
+    assert all(x.status == "CONFIRMED" for x in evidence)
+
+def test_context_agent_and_portal(tmp_path):
+    root=fixture_repo(tmp_path); context=build(root, {"nodes":[{"name":"UserController","path":"app/Http/UserController.php","type":"controller"}]})
+    assert context["schema_version"] == "0.2" and context["architecture"]["status"] == "INFERRED"
+    agent=render_agent(context); page=render_portal(context, agent, ["graph.html"])
+    assert "Instrucciones para el Agente" in agent and "Copiar contexto" in page and "Abrir grafo técnico" in page
+
+def test_exclude_klap_is_idempotent(tmp_path, monkeypatch):
+    root=fixture_repo(tmp_path)
+    monkeypatch.setattr("klapcontext.git.run_git", lambda root,*args: ".git" if args == ("rev-parse", "--git-dir") else "true")
+    exclude_klap(root); exclude_klap(root)
+    assert (root/".git/info/exclude").read_text().splitlines().count(".klap/") == 1
+
+def test_status_marks_matching_clean_context_current(tmp_path, monkeypatch, capsys):
+    (tmp_path/".klap").mkdir()
+    (tmp_path/".klap"/"state.json").write_text(json.dumps({"git_commit":"abc"}))
+    monkeypatch.setattr(cli, "commit", lambda root: "abc")
+    monkeypatch.setattr(cli, "dirty_files", lambda root: [])
+    assert cli.cmd_status(type("Args", (), {"path":str(tmp_path)})()) == 0
+    assert "CURRENT" in capsys.readouterr().out
+
+def test_system_model_reads_docs_routes_scheduler_and_deployment(tmp_path):
+    root=fixture_repo(tmp_path)
+    (root/"README.md").write_text("# Contact processor\n\nProcesses customer audio through a local API.")
+    (root/"routes"/"api.php").write_text("Route::post('/audio', [AudioController::class, 'store']);")
+    (root/"routes"/"console.php").write_text("Schedule::command('audio:send')->everyThirtyMinutes();")
+    (root/"docker-compose.yml").write_text("services:\n  app:\n    ports: ['8010:80']")
+    context=build(root, {"nodes":[]}); system=context["system_model"]
+    assert system["purpose"]["text"] == "Processes customer audio through a local API."
+    assert any(item["type"] == "http" for item in system["entry_points"])
+    assert system["background_processes"] and "Docker Compose" in system["deployment"]["tools"]
+    assert any(item["intent"] == "Entender la API HTTP" for item in system["start_here"])