kodebrain 0.1.0__py3-none-any.whl

kodebrain/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

kodebrain/cli.py

@@ -0,0 +1,116 @@
+"""
+kodebrain CLI — install agent instructions and git hooks.
+
+Usage:
+  kodebrain install [path] [--platform all|claude|cursor|copilot|windsurf|cline]
+  kodebrain uninstall [path]
+  kodebrain hook install [path]
+  kodebrain hook uninstall [path]
+  kodebrain hook status [path]
+"""
+
+from __future__ import annotations
+import argparse
+import sys
+from pathlib import Path
+
+from kodebrain.install import PLATFORMS, install, uninstall
+from kodebrain import hook as _hook
+
+
+ALL_PLATFORMS = list(PLATFORMS.keys())
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    root = Path(args.path).resolve()
+    platforms = ALL_PLATFORMS if args.platform == "all" else [args.platform]
+
+    try:
+        written = install(root, platforms)
+    except RuntimeError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    print(f"Kode Brain installed in {root.name}/")
+    for f in written:
+        label = next(
+            (PLATFORMS[p]["label"] for p in PLATFORMS if PLATFORMS[p]["file"] == f),
+            f,
+        )
+        print(f"  ✓ {f}  ({label})")
+    return 0
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    root = Path(args.path).resolve()
+    changed = uninstall(root)
+
+    if not changed:
+        print("No Kode Brain blocks found — nothing to remove.")
+        return 0
+
+    print(f"Kode Brain removed from {root.name}/")
+    for f in changed:
+        print(f"  ✓ {f}")
+    return 0
+
+
+def cmd_hook(args: argparse.Namespace) -> int:
+    root = Path(args.path).resolve()
+
+    if not (root / ".git").is_dir():
+        print(f"error: {root} is not a git repository.", file=sys.stderr)
+        return 1
+
+    if args.hook_cmd == "install":
+        path = _hook.install(root)
+        print(f"Hook installed: {path}")
+    elif args.hook_cmd == "uninstall":
+        removed = _hook.uninstall(root)
+        print("Hook removed." if removed else "Hook not installed — nothing to remove.")
+    elif args.hook_cmd == "status":
+        installed = _hook.status(root)
+        print(f"Hook {'installed' if installed else 'not installed'}.")
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="kodebrain",
+        description="Kode Brain — install agent instructions across AI platforms.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # install
+    p_install = sub.add_parser("install", help="Write KB instruction blocks to platform config files.")
+    p_install.add_argument("path", nargs="?", default=".", help="Project root (default: current directory)")
+    p_install.add_argument(
+        "--platform",
+        choices=["all"] + ALL_PLATFORMS,
+        default="all",
+        help="Target platform (default: all)",
+    )
+
+    # uninstall
+    p_uninstall = sub.add_parser("uninstall", help="Remove all KB instruction blocks.")
+    p_uninstall.add_argument("path", nargs="?", default=".", help="Project root (default: current directory)")
+
+    # hook
+    p_hook = sub.add_parser("hook", help="Manage the git post-commit hook.")
+    hook_sub = p_hook.add_subparsers(dest="hook_cmd", required=True)
+    for hcmd in ("install", "uninstall", "status"):
+        hp = hook_sub.add_parser(hcmd)
+        hp.add_argument("path", nargs="?", default=".", help="Project root (default: current directory)")
+
+    args = parser.parse_args()
+
+    if args.command == "install":
+        sys.exit(cmd_install(args))
+    elif args.command == "uninstall":
+        sys.exit(cmd_uninstall(args))
+    elif args.command == "hook":
+        sys.exit(cmd_hook(args))
+
+
+if __name__ == "__main__":
+    main()

kodebrain/hook.py

@@ -0,0 +1,90 @@
+"""
+Git post-commit hook that marks KB-tracked source files as dirty
+after each commit, so the next /kodebrain scan knows what changed.
+
+The hook does NOT run the LLM — it only updates file-hashes.json
+so scan can detect drift deterministically.
+"""
+
+from __future__ import annotations
+import os
+import re
+import stat
+import subprocess
+from pathlib import Path
+
+HOOK_START = "# kodebrain:start"
+HOOK_END = "# kodebrain:end"
+HOOK_FILE = ".git/hooks/post-commit"
+_HOOK_RE = re.compile(
+    r"\n?" + re.escape(HOOK_START) + r".*?" + re.escape(HOOK_END) + r"\n?",
+    re.DOTALL,
+)
+
+_HOOK_BODY = """\
+# kodebrain:start
+# Kode Brain — mark changed source files as dirty in file-hashes.json
+# Run /kodebrain scan in Claude Code to refresh KB pages after significant changes.
+_KB_HASHES=$(ls docs/brain/projects/*/graph/file-hashes.json 2>/dev/null | head -1)
+if [ -n "$_KB_HASHES" ]; then
+  _CHANGED=$(git diff --name-only HEAD~1 2>/dev/null | grep -E '\\.(ts|tsx|js|jsx|py|go|rs|java|rb|swift|kt)$' | head -30)
+  if [ -n "$_CHANGED" ]; then
+    python3 -c "
+import json, hashlib, sys
+from pathlib import Path
+hashes_path = Path('$_KB_HASHES')
+if not hashes_path.exists():
+    sys.exit(0)
+hashes = json.loads(hashes_path.read_text())
+changed = [f for f in '''$_CHANGED'''.strip().split() if f]
+for f in changed:
+    p = Path(f)
+    if p.exists():
+        hashes[f] = hashlib.sha256(p.read_bytes()).hexdigest()
+    elif f in hashes:
+        del hashes[f]
+hashes_path.write_text(json.dumps(hashes, indent=2))
+" 2>/dev/null || true
+  fi
+fi
+# kodebrain:end"""
+
+
+def install(root: Path) -> str:
+    hook_path = root / HOOK_FILE
+    hook_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing = hook_path.read_text(encoding="utf-8") if hook_path.exists() else ""
+
+    if HOOK_START in existing:
+        new_content = _HOOK_RE.sub("", existing).rstrip("\n") + "\n\n" + _HOOK_BODY + "\n"
+    elif existing.strip():
+        new_content = existing.rstrip("\n") + "\n\n" + _HOOK_BODY + "\n"
+    else:
+        new_content = "#!/bin/sh\n\n" + _HOOK_BODY + "\n"
+
+    hook_path.write_text(new_content, encoding="utf-8")
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    return HOOK_FILE
+
+
+def uninstall(root: Path) -> bool:
+    hook_path = root / HOOK_FILE
+    if not hook_path.exists():
+        return False
+    original = hook_path.read_text(encoding="utf-8")
+    if HOOK_START not in original:
+        return False
+    cleaned = _HOOK_RE.sub("", original).rstrip("\n")
+    if cleaned and cleaned.strip() != "#!/bin/sh":
+        hook_path.write_text(cleaned + "\n", encoding="utf-8")
+    else:
+        hook_path.unlink()
+    return True
+
+
+def status(root: Path) -> bool:
+    hook_path = root / HOOK_FILE
+    if not hook_path.exists():
+        return False
+    return HOOK_START in hook_path.read_text(encoding="utf-8")

kodebrain/install.py

@@ -0,0 +1,179 @@
+"""
+Write/remove Kode Brain agent instruction blocks in platform config files.
+
+Each platform gets a tagged block:
+  <!-- kodebrain:start -->
+  ...instructions...
+  <!-- kodebrain:end -->
+
+The block is idempotent — install twice, update safely. Uninstall removes it cleanly.
+"""
+
+from __future__ import annotations
+import re
+from pathlib import Path
+
+BLOCK_START = "<!-- kodebrain:start -->"
+BLOCK_END = "<!-- kodebrain:end -->"
+_BLOCK_RE = re.compile(
+    r"\n?" + re.escape(BLOCK_START) + r".*?" + re.escape(BLOCK_END) + r"\n?",
+    re.DOTALL,
+)
+
+# ---------------------------------------------------------------------------
+# Platform definitions
+# ---------------------------------------------------------------------------
+
+PLATFORMS = {
+    "claude": {
+        "file": "CLAUDE.md",
+        "label": "Claude Code",
+        "create_if_missing": True,
+    },
+    "cursor": {
+        "file": ".cursor/rules/kodebrain.mdc",
+        "label": "Cursor",
+        "create_if_missing": True,
+    },
+    "copilot": {
+        "file": ".github/copilot-instructions.md",
+        "label": "GitHub Copilot",
+        "create_if_missing": True,
+    },
+    "windsurf": {
+        "file": ".windsurfrules",
+        "label": "Windsurf",
+        "create_if_missing": True,
+    },
+    "cline": {
+        "file": ".clinerules",
+        "label": "Cline",
+        "create_if_missing": True,
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Block content
+# ---------------------------------------------------------------------------
+
+def _claude_block(name: str) -> str:
+    return f"""{BLOCK_START}
+## Kode Brain — Knowledge Base
+
+This project has a structured knowledge map at `docs/brain/projects/{name}/`.
+
+**Session start:** Run `/kodebrain reading-pack "<task>"` before touching any code.
+It returns the relevant domain pages, source file hints, and active warnings — 3–25× cheaper than navigating source files cold.
+
+**After editing source files:** Run `/kodebrain update --files <f1> <f2>` to keep the KB current.
+Subsequent queries return fresh data, not pre-edit state.
+
+**For questions:** Run `/kodebrain query "<question>"` instead of reading raw source files.
+
+**KB-first rule:** Use KB pages as primary source of truth.
+Read source files directly only when making a targeted edit or when a node is `confidence: stale`.
+
+KB location:  `docs/brain/projects/{name}/`
+Graph view:   Open `docs/brain/` as an Obsidian vault.
+{BLOCK_END}"""
+
+
+def _generic_block(name: str) -> str:
+    return f"""{BLOCK_START}
+## Kode Brain — Knowledge Base
+
+This project has a structured knowledge map at `docs/brain/projects/{name}/`.
+
+**Before starting any task:**
+1. Read `docs/brain/projects/{name}/{name}.md` — project hub with all domains.
+2. Read the domain hub(s) for areas you'll touch: `docs/brain/projects/{name}/domains/<domain>/<domain>.md`.
+3. Check `docs/brain/projects/{name}/reports/reading-packs/` for a pre-built context pack matching your task.
+
+**KB-first rule:** Use KB pages as primary source of truth.
+Read source files directly only for targeted edits or when a page shows `confidence: stale`.
+
+**After editing source files:**
+The KB may drift from source. Check `docs/brain/projects/{name}/graph/file-hashes.json`
+to identify which files changed. Run `/kodebrain scan` in Claude Code to refresh the KB.
+
+KB location:  `docs/brain/projects/{name}/`
+{BLOCK_END}"""
+
+
+def _make_block(platform: str, name: str) -> str:
+    if platform == "claude":
+        return _claude_block(name)
+    return _generic_block(name)
+
+
+# ---------------------------------------------------------------------------
+# KB discovery
+# ---------------------------------------------------------------------------
+
+def find_kb_name(root: Path) -> str | None:
+    """Return the project name by scanning docs/brain/projects/."""
+    projects_dir = root / "docs" / "brain" / "projects"
+    if not projects_dir.is_dir():
+        return None
+    for child in projects_dir.iterdir():
+        if child.is_dir() and (child / "graph" / "nodes.json").exists():
+            return child.name
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Install / uninstall
+# ---------------------------------------------------------------------------
+
+def install(root: Path, platforms: list[str]) -> list[str]:
+    """Write KB instruction blocks. Returns list of files written."""
+    name = find_kb_name(root)
+    if name is None:
+        raise RuntimeError(
+            "No Kode Brain KB found in docs/brain/projects/. "
+            "Run /kodebrain init first."
+        )
+
+    written: list[str] = []
+    for platform in platforms:
+        cfg = PLATFORMS[platform]
+        target = root / cfg["file"]
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        existing = target.read_text(encoding="utf-8") if target.exists() else ""
+        block = _make_block(platform, name)
+
+        if BLOCK_START in existing:
+            # Replace existing block
+            new_content = _BLOCK_RE.sub("", existing).rstrip("\n") + "\n\n" + block + "\n"
+        elif existing.strip():
+            # Append to existing file
+            new_content = existing.rstrip("\n") + "\n\n" + block + "\n"
+        else:
+            # New file
+            new_content = block + "\n"
+
+        target.write_text(new_content, encoding="utf-8")
+        written.append(str(target.relative_to(root)))
+
+    return written
+
+
+def uninstall(root: Path) -> list[str]:
+    """Remove KB blocks from all platform files. Returns list of files changed."""
+    changed: list[str] = []
+    for cfg in PLATFORMS.values():
+        target = root / cfg["file"]
+        if not target.exists():
+            continue
+        original = target.read_text(encoding="utf-8")
+        if BLOCK_START not in original:
+            continue
+        cleaned = _BLOCK_RE.sub("", original).rstrip("\n")
+        if cleaned:
+            target.write_text(cleaned + "\n", encoding="utf-8")
+        else:
+            target.unlink()
+        changed.append(str(target.relative_to(root)))
+    return changed

kodebrain-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: kodebrain
+Version: 0.1.0
+Summary: Living knowledge map for codebases — install agent instructions across AI platforms
+Project-URL: Homepage, https://github.com/mekku/kb-builder
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kb-builder
+
+**Kode Brain** — a living knowledge system for evolving software projects.
+
+Converts an imperfect, growing codebase into a structured, searchable knowledge map of domains, capabilities, concepts, flows, runtime behavior, dependencies, legacy areas, migration states, and source evidence — so humans and AI agents can understand and modify the system without rediscovering everything from scratch.
+
+## Design Documents
+
+| Document | Purpose |
+|---|---|
+| [Taxonomy](docs/design/taxonomy.md) | Finalized node types, edge types, status labels, confidence labels |
+| [Skills](docs/design/skills.md) | Skill API contracts — inputs, outputs, guarantees |
+| [Agents](docs/design/agents.md) | Agent role boundaries — responsibilities, allowed skills, forbidden actions |
+| [Workflows](docs/design/workflows.md) | Core workflow sequence diagrams |
+| [Open Decisions](docs/design/open-decisions.md) | Unresolved architectural decisions |
+
+## Schemas
+
+| File | Purpose |
+|---|---|
+| [schema/node.schema.json](schema/node.schema.json) | JSON Schema for KnowledgeNode |
+| [schema/edge.schema.json](schema/edge.schema.json) | JSON Schema for KnowledgeEdge |
+| [schema/knowledge-base.schema.json](schema/knowledge-base.schema.json) | Top-level graph container schema |
+
+## Design Order
+
+Per the Kode Brain spec (§20.7):
+
+```
+Taxonomy → Workflow → Skills → Agents → Plugin/CLI
+```
+
+This repository is currently at the **design phase**. Implementation comes after the design is validated.
+
+## Commands
+
+```
+/kodebrain init [path]                     Scan project, scaffold docs/kodebrain/
+/kodebrain scan [path]                     Re-scan and update knowledge graph
+/kodebrain query "<task or symptom>"       Query the KB by task description
+/kodebrain reading-pack "<task>"           Generate + save a context pack
+/kodebrain detect-legacy [--domain slug]   Flag suspected dead code
+/kodebrain review [--page path]            Review KB pages for stale claims
+/kodebrain update [--diff] [--files ...]   Update KB from changed files
+```
+
+## Installation
+
+The skill must be installed into Claude Code's skills directory:
+
+```bash
+# From the repo root
+ln -s "$(pwd)" ~/.claude/skills/kodebrain
+```
+
+After symlinking, `SKILL.md` is discoverable by Claude Code and `/kodebrain` becomes available in any Claude Code session.

kodebrain-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+kodebrain/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+kodebrain/cli.py,sha256=WGuvRWbT6ZSSXGYeMrBUEklXMinyxkm-qU0rgz5aDHw,3569
+kodebrain/hook.py,sha256=SydLKkho0tyUi13_RJt-OL4xCcEALwu4o37GD-pVG24,2854
+kodebrain/install.py,sha256=gyqODHXmubCQEjYPm0jFIASM6xyD6Bpomx7uJqWNQVM,6097
+kodebrain-0.1.0.dist-info/METADATA,sha256=NniPdUODjsSO_ROz2D4Qg35-7Td2xlMyQ5uYO15XAkU,2618
+kodebrain-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+kodebrain-0.1.0.dist-info/entry_points.txt,sha256=ANdDDnzUVgeAX5QIxThWzGL9_8wyYFJSGAY93UXaWiE,49
+kodebrain-0.1.0.dist-info/RECORD,,

kodebrain-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kodebrain-0.1.0.dist-info/entry_points.txt

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