raidlock 0.1.0__py3-none-any.whl

raidlock/lore/vault.py

@@ -0,0 +1,264 @@
+import contextlib
+import os
+import re
+
+from ..core import redact, store
+from ..core.errors import Precondition
+from ..core.lock import FileLock
+from . import frontmatter as F
+
+LESSONS = "lessons"
+PENDING = ".pending"
+HUBS = "hubs"
+STATE = ".state.json"
+TEXT_MAX = 200
+LINKED_PATHS = 3
+FIELDS = (
+    "type",
+    "id",
+    "created",
+    "workspace",
+    "workspace_uid",
+    "repo",
+    "paths",
+    "card",
+    "agent",
+    "provider",
+    "model",
+    "source",
+    "source_id",
+    "tags",
+    "hits",
+    "last_used",
+    "status",
+    "proposed_by",
+    "approved_by",
+    "approved_at",
+)
+HUB_KINDS = ("card", "agent", "repo", "path")
+
+
+def validate_id(value):
+    if not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{12}", value) is None:
+        raise Precondition("invalid lesson id: expected 12 lowercase hexadecimal characters")
+    return value
+
+
+def validate_folder(folder):
+    if folder not in (LESSONS, PENDING):
+        raise Precondition("invalid lesson folder")
+    return folder
+
+
+def slug(text):
+    """Lowercase [a-z0-9-] form for hub note names."""
+    return re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", (text or "").lower())).strip("-") or "x"
+
+
+def one_line(text, limit=TEXT_MAX):
+    text = " ".join(redact(text or "").replace("[[", "[").replace("]]", "]").split())
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def hubs_of(lesson):
+    """Hub note names a lesson links to, by kind."""
+    out = {"card": [], "agent": [], "repo": [], "path": []}
+    if lesson.get("card"):
+        out["card"].append("card-" + slug(lesson["card"]))
+    if lesson.get("agent"):
+        out["agent"].append("agent-" + slug(lesson["agent"]))
+    if lesson.get("repo"):
+        out["repo"].append("repo-" + slug(lesson["repo"]))
+    for p in lesson.get("paths", [])[:LINKED_PATHS]:
+        out["path"].append("path-" + slug(p))
+    return out
+
+
+def body(lesson):
+    h = hubs_of(lesson)
+    head = [lesson["source"]] + [f"[[{n}]]" for k in ("card", "agent", "repo") for n in h[k]]
+    lines = [lesson["text"], " · ".join(head)]
+    if h["path"]:
+        lines.append("paths: " + " ".join(f"[[{n}]]" for n in h["path"]))
+    return "\n".join(lines)
+
+
+def render(lesson):
+    meta = {k: lesson.get(k, "") for k in FIELDS}
+    meta["type"] = "lesson"
+    meta["paths"] = list(lesson.get("paths", []))
+    meta["tags"] = list(lesson.get("tags", []))
+    meta["hits"] = int(lesson.get("hits", 0))
+    return F.dump(meta, body(lesson))
+
+
+def from_note(text):
+    meta, rest = F.parse(text)
+    if meta.get("type") != "lesson":
+        return None
+    validate_id(meta.get("id"))
+    lesson = dict(meta)
+    lesson["text"] = rest.split("\n", 1)[0]
+    return lesson
+
+
+class Vault:
+    """An Obsidian-compatible folder: lessons/lesson-<id>.md plus generated hub notes under hubs/."""
+
+    def __init__(self, root, lock=None):
+        self.root = root
+        self._lock = lock
+
+    @classmethod
+    def for_board(cls, board):
+        return cls(os.path.join(board.dir, "lore"), lock=board.lock)
+
+    @classmethod
+    def global_(cls, home):
+        root = os.path.join(home, "lore")
+        return cls(root, lock=lambda: FileLock(os.path.join(root, ".lock")))
+
+    @contextlib.contextmanager
+    def locked(self):
+        os.makedirs(self.root, exist_ok=True)
+        if self._lock is None:
+            yield
+            return
+        with self._lock():
+            yield
+
+    def _path(self, *parts):
+        path = os.path.abspath(os.path.join(self.root, *parts))
+        if os.path.commonpath([os.path.abspath(self.root), path]) != os.path.abspath(self.root):
+            raise Precondition("invalid vault path")
+        return path
+
+    def lesson_path(self, lesson_id, folder=LESSONS):
+        return self._path(validate_folder(folder), f"lesson-{validate_id(lesson_id)}.md")
+
+    def _note_path(self, rel):
+        parts = rel.split(os.sep)
+        if len(parts) != 2 or parts[0] not in (LESSONS, PENDING, HUBS) or parts[1] in (".", ".."):
+            raise Precondition("invalid vault path")
+        if parts[0] in (LESSONS, PENDING) and not re.fullmatch(r"lesson-[0-9a-f]{12}\.md", parts[1]):
+            raise Precondition("invalid lesson id")
+        return self._path(rel)
+
+    def _validate_note(self, rel, text):
+        folder, name = rel.split(os.sep)
+        if folder in (LESSONS, PENDING):
+            lesson = from_note(text)
+            if not lesson or name != f"lesson-{lesson['id']}.md":
+                raise Precondition("lesson id does not match filename")
+
+    def write(self, rel, text):
+        path = self._note_path(rel)
+        self._validate_note(rel, text)
+        store.atomic_write_text(path, text)
+
+    def has(self, lesson_id, folder=LESSONS):
+        return os.path.exists(self.lesson_path(lesson_id, folder))
+
+    def get(self, lesson_id, folder=LESSONS):
+        try:
+            with open(self.lesson_path(lesson_id, folder), encoding="utf-8") as f:
+                lesson = from_note(f.read())
+                if lesson and lesson["id"] != lesson_id:
+                    raise Precondition("lesson id does not match filename")
+                return lesson
+        except (FileNotFoundError, F.FrontmatterError):
+            return None
+
+    def put(self, lesson, folder=LESSONS):
+        self.lesson_path(lesson["id"], folder)
+        self.write(os.path.join(folder, f"lesson-{lesson['id']}.md"), render(lesson))
+
+    def drop(self, lesson_id, folder=LESSONS):
+        try:
+            os.remove(self.lesson_path(lesson_id, folder))
+            return True
+        except FileNotFoundError:
+            return False
+
+    def pending(self):
+        """Lessons waiting for lead approval. Kept in a dot folder, so Obsidian does not show them."""
+        return self.lessons(PENDING)
+
+    def lessons(self, folder=LESSONS):
+        validate_folder(folder)
+        try:
+            names = sorted(os.listdir(self._path(folder)))
+        except FileNotFoundError:
+            return []
+        out = []
+        for name in names:
+            if not re.fullmatch(r"lesson-[0-9a-f]{12}\.md", name):
+                continue
+            try:
+                lesson = self.get(name[7:-3], folder)
+            except (OSError, Precondition):
+                continue
+            if lesson:
+                out.append(lesson)
+        return out
+
+    def state(self):
+        return store.read_json(self._path(STATE), {}) or {}
+
+    def save_state(self, data):
+        store.write_json(self._path(STATE), {"schema": store.SCHEMA, **data})
+
+    def rebuild_hubs(self, lessons=None):
+        """Regenerate every hub note from the lessons and remove hubs nothing links to any more."""
+        lessons = [x for x in self.lessons() if x.get("status") != "retired"] if lessons is None else lessons
+        groups = {}
+        for lesson in lessons:
+            validate_id(lesson.get("id"))
+            for kind, names in hubs_of(lesson).items():
+                for name in names:
+                    groups.setdefault((kind, name), []).append(lesson)
+        wanted = set()
+        for (kind, name), items in sorted(groups.items()):
+            rel = os.path.join(HUBS, f"{name}.md")
+            wanted.add(f"{name}.md")
+            lines = [f"# {name}", ""] + [
+                f"- [[lesson-{x['id']}]] {x['text']}"
+                for x in sorted(items, key=lambda x: (x.get("created", ""), x["id"]))
+            ]
+            text = F.dump(
+                {"type": "hub", "hub": kind, "name": name, "lessons": len(items), "generated": True}, "\n".join(lines)
+            )
+            if self._read(rel) != text:
+                self.write(rel, text)
+        folder = self._path(HUBS)
+        if os.path.isdir(folder):
+            for n in os.listdir(folder):
+                if n.endswith(".md") and n not in wanted:
+                    os.remove(os.path.join(folder, n))
+        return len(wanted)
+
+    def _read(self, rel):
+        path = self._note_path(rel)
+        try:
+            with open(path, encoding="utf-8") as f:
+                text = f.read()
+        except FileNotFoundError:
+            return None
+        self._validate_note(rel, text)
+        return text
+
+    def notes(self):
+        """Every Markdown note in the vault as (relative path, text)."""
+        out = []
+        for base, dirs, files in os.walk(self.root):
+            dirs[:] = sorted(d for d in dirs if not d.startswith("."))
+            for n in sorted(files):
+                if n.endswith(".md"):
+                    p = os.path.join(base, n)
+                    rel = os.path.relpath(p, self.root)
+                    try:
+                        text = self._read(rel)
+                    except (Precondition, F.FrontmatterError):
+                        continue
+                    out.append((rel, text))
+        return out

raidlock/mcp/__init__.py

@@ -0,0 +1,34 @@
+def register_cli(add_command):
+    add_command("mcp", "serve this board to MCP clients over stdio", _setup, _handle)
+
+
+def _setup(parser):
+    parser.add_argument(
+        "--workspace",
+        default=None,
+        help="workspace or .board folder to serve; MCP clients start servers in their own working folder",
+    )
+    return parser
+
+
+def _handle(ctx, args):
+    from ..core import find_board_dir
+    from .server import run
+
+    path = args.workspace or args.board
+    board_path = find_board_dir(path) if path else None
+    return {"_exit": run(board_path=board_path)}, ""
+
+
+def register_tokens(register):
+    register("mcp tool schemas", _schema_tokens)
+
+
+def _schema_tokens(board):
+    import json
+
+    from ..core.tokens import estimate
+    from .tools import TOOLS
+
+    text = json.dumps(TOOLS, separators=(",", ":"))
+    return {"tokens": estimate(text), "detail": f"{len(TOOLS)} tools, {len(text)} chars (only when MCP is enabled)"}

raidlock/mcp/resources.py

@@ -0,0 +1,72 @@
+import json
+from urllib.parse import quote, unquote
+
+from ..core.errors import Precondition
+from ..core.leases import is_live
+from ..core.transcript import _clean, redact
+
+SCHEME = "raidlock://"
+
+
+def uri(board, *parts):
+    return SCHEME + "/".join(quote(p, safe="") for p in (board.name, *parts))
+
+
+def listing(board):
+    out = [
+        {
+            "uri": uri(board, "leases"),
+            "name": "leases",
+            "description": "Live leases on this board.",
+            "mimeType": "application/json",
+        }
+    ]
+    for c in board.cards():
+        if c["lane"] != "done":
+            out.append(
+                {"uri": uri(board, "card", c["id"]), "name": c["id"], "title": c["title"], "mimeType": "text/markdown"}
+            )
+    return _clean(out)
+
+
+def templates(board):
+    return [
+        {
+            "uriTemplate": SCHEME + quote(board.name, safe="") + "/card/{id}",
+            "name": "card",
+            "description": "A card's brief.",
+            "mimeType": "text/markdown",
+        }
+    ]
+
+
+def read(board, target):
+    if not isinstance(target, str) or not target.startswith(SCHEME):
+        raise Precondition("unknown resource", uri=target)
+    parts = [unquote(p) for p in target[len(SCHEME) :].split("/")]
+    if parts[0] != board.name:
+        raise Precondition(f"this server serves workspace {board.name}", uri=target)
+    if parts[1:] == ["leases"]:
+        return "application/json", json.dumps(leases(board), separators=(",", ":"), ensure_ascii=False)
+    if len(parts) == 3 and parts[1] == "card" and parts[2]:
+        return "text/markdown", brief(board, parts[2])
+    raise Precondition("unknown resource", uri=target)
+
+
+def leases(board):
+    out = []
+    for cid, lease in sorted(board.leases().items()):
+        out.append(
+            {
+                "card": cid,
+                "agent": lease.get("agent", ""),
+                "paths": lease.get("paths", []),
+                "expires": lease.get("expires"),
+                "live": is_live(lease),
+            }
+        )
+    return _clean(out)
+
+
+def brief(board, card_id):
+    return redact(board.brief(card_id)["text"])

raidlock/mcp/server.py

@@ -0,0 +1,184 @@
+import io
+import json
+import sys
+
+from .. import __version__
+from ..core import db
+from ..core.errors import RaidlockError
+from ..core.transcript import _clean
+from . import resources
+from .tools import TOOLS, Session
+
+MODERN = ("2026-07-28",)
+LEGACY = ("2025-11-25", "2025-06-18", "2025-03-26")
+META = "io.modelcontextprotocol/"
+INFO = {"name": "raidlock", "version": __version__}
+CAPABILITIES = {"tools": {}, "resources": {}}
+INSTRUCTIONS = (
+    "raidlock board for this workspace. claimable, then claim a card, note progress, move it to review. "
+    "Edit only paths your card locks."
+)
+PARSE_ERROR, INVALID_REQUEST, NO_METHOD, INVALID_PARAMS, INTERNAL = -32700, -32600, -32601, -32602, -32603
+UNSUPPORTED_VERSION = -32022
+
+
+class RpcError(Exception):
+    def __init__(self, code, message, data=None):
+        super().__init__(message)
+        self.code, self.message, self.data = code, message, data
+
+
+def compact(value):
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False, default=str)
+
+
+class Server:
+    def __init__(self, board_path=None, env=None):
+        self.session = Session(board_path, env)
+        self.legacy = None
+
+    def handle(self, msg):
+        return _clean(self._handle(msg))
+
+    def _handle(self, msg):
+        if not isinstance(msg, dict) or msg.get("jsonrpc") != "2.0" or not isinstance(msg.get("method"), str):
+            if isinstance(msg, dict) and "method" not in msg and ("result" in msg or "error" in msg):
+                return None
+            return _error(msg.get("id") if isinstance(msg, dict) else None, INVALID_REQUEST, "invalid request")
+        if "id" not in msg:
+            return None
+        rid, method = msg["id"], msg["method"]
+        params = msg.get("params", {})
+        try:
+            if not isinstance(params, dict):
+                raise RpcError(INVALID_PARAMS, "params must be an object")
+            modern = self._era(method, params)
+            result = self.dispatch(method, params)
+        except RpcError as e:
+            return _error(rid, e.code, e.message, e.data)
+        except Exception as e:
+            return _error(rid, INTERNAL, f"internal error: {e}")
+        result.setdefault("resultType", "complete")
+        if modern:
+            result.setdefault("_meta", {})[META + "serverInfo"] = INFO
+        return {"jsonrpc": "2.0", "id": rid, "result": result}
+
+    def _era(self, method, params):
+        meta = params.get("_meta") if isinstance(params.get("_meta"), dict) else {}
+        version = meta.get(META + "protocolVersion")
+        if method in ("initialize", "ping") and version is None:
+            return False
+        if version is not None:
+            if version not in MODERN:
+                raise RpcError(
+                    UNSUPPORTED_VERSION,
+                    "Unsupported protocol version",
+                    {"supported": list(MODERN), "requested": version},
+                )
+            if not isinstance(meta.get(META + "clientCapabilities"), dict):
+                raise RpcError(INVALID_PARAMS, f"missing _meta {META}clientCapabilities")
+            return True
+        if method == "server/discover" or self.legacy:
+            return method == "server/discover"
+        raise RpcError(
+            INVALID_PARAMS,
+            f"missing _meta {META}protocolVersion; send initialize first or use one of {', '.join(MODERN)}",
+            {"supported": list(MODERN)},
+        )
+
+    def dispatch(self, method, params):
+        if method == "initialize":
+            requested = params.get("protocolVersion")
+            self.legacy = requested if requested in LEGACY else LEGACY[0]
+            return {
+                "protocolVersion": self.legacy,
+                "capabilities": CAPABILITIES,
+                "serverInfo": INFO,
+                "instructions": INSTRUCTIONS,
+            }
+        if method == "ping":
+            return {}
+        if method == "server/discover":
+            return {
+                "supportedVersions": list(MODERN),
+                "capabilities": CAPABILITIES,
+                "_meta": {META + "serverInfo": INFO},
+                "instructions": INSTRUCTIONS,
+                "ttlMs": 3600000,
+                "cacheScope": "public",
+            }
+        if method == "tools/list":
+            return {"tools": TOOLS, "ttlMs": 3600000, "cacheScope": "public"}
+        if method == "tools/call":
+            return self.call_tool(params)
+        if method == "resources/list":
+            return {"resources": resources.listing(self._board()), "ttlMs": 0, "cacheScope": "private"}
+        if method == "resources/templates/list":
+            return {"resourceTemplates": resources.templates(self._board()), "ttlMs": 3600000, "cacheScope": "private"}
+        if method == "resources/read":
+            board = self._board()
+            try:
+                mime, text = resources.read(board, params.get("uri"))
+            except RaidlockError as e:
+                raise RpcError(INVALID_PARAMS, e.message, {"uri": params.get("uri")}) from e
+            return {
+                "contents": [{"uri": params["uri"], "mimeType": mime, "text": text}],
+                "ttlMs": 0,
+                "cacheScope": "private",
+            }
+        raise RpcError(NO_METHOD, f"method not found: {method}")
+
+    def _board(self):
+        try:
+            return self.session.board()
+        except RaidlockError as e:
+            raise RpcError(INVALID_PARAMS, e.message, e.to_dict()) from e
+
+    def call_tool(self, params):
+        name = params.get("name")
+        if not isinstance(name, str) or name not in {t["name"] for t in TOOLS}:
+            raise RpcError(INVALID_PARAMS, f"Unknown tool: {name}")
+        arguments = params.get("arguments", {})
+        if not isinstance(arguments, dict):
+            raise RpcError(INVALID_PARAMS, "arguments must be an object")
+        try:
+            out, is_error = self.session.call(name, arguments), False
+        except RaidlockError as e:
+            out, is_error = e.to_dict(), True
+            out.pop("ok", None)
+        return {"content": [{"type": "text", "text": compact(out)}], "isError": is_error}
+
+
+def _error(rid, code, message, data=None):
+    err = {"code": code, "message": message}
+    if data is not None:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "id": rid, "error": err}
+
+
+def serve(inp, out, board_path=None, env=None):
+    server = Server(board_path, env)
+    for raw in inp:
+        line = raw.decode("utf-8", "replace") if isinstance(raw, bytes) else raw
+        if not line.strip():
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            reply = _error(None, PARSE_ERROR, "parse error")
+        else:
+            with db.released():
+                reply = server.handle(msg)
+        if reply is not None:
+            data = compact(reply) + "\n"
+            out.write(data.encode("utf-8") if _binary(out) else data)
+            out.flush()
+    return 0
+
+
+def _binary(stream):
+    return not isinstance(stream, io.TextIOBase)
+
+
+def run(board_path=None, env=None):
+    return serve(sys.stdin.buffer, sys.stdout.buffer, board_path, env)