brainkeeper 0.1.0__py3-none-any.whl

brainkeeper/__init__.py

@@ -0,0 +1,3 @@
+"""brainkeeper: structured Markdown vault standard with engine, MCP, and CLI."""
+
+__version__ = "0.1.0"

brainkeeper/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from brainkeeper.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

brainkeeper/cli/__init__.py

@@ -0,0 +1,45 @@
+"""brainkeeper CLI dispatcher."""
+
+from __future__ import annotations
+import argparse
+import sys
+from pathlib import Path
+
+from . import serve as _serve
+from . import init as _init
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="brainkeeper",
+        description="brainkeeper vault tooling",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    sp_serve = sub.add_parser("serve", help="Start the MCP server")
+    sp_serve.add_argument(
+        "--vault",
+        type=Path,
+        required=True,
+        help="Path to vault root containing brainkeeper.yaml",
+    )
+    sp_serve.add_argument("-v", "--verbose", action="store_true")
+
+    sp_init = sub.add_parser("init", help="Bootstrap a new vault")
+    sp_init.add_argument(
+        "path", type=Path, help="Path for the new vault root (created if absent)"
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        return _serve.run(args)
+    if args.command == "init":
+        return _init.run(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

brainkeeper/cli/init.py

@@ -0,0 +1,52 @@
+"""vault init subcommand."""
+
+from __future__ import annotations
+import importlib.resources
+import sys
+from pathlib import Path
+
+_LAYER_DIRS = [
+    "00 Inbox",
+    "10 Journal",
+    "20 Projects",
+    "30 Areas",
+    "40 Brain",
+    "90 Archive",
+]
+
+
+def _find_minimal_yaml() -> Path:
+    via_package = Path(
+        str(importlib.resources.files("brainkeeper.spec") / "examples" / "minimal.yaml")
+    )
+    if via_package.exists():
+        return via_package
+    # Dev fallback
+    dev_path = (
+        Path(__file__).resolve().parents[3] / "spec" / "examples" / "minimal.yaml"
+    )
+    if dev_path.exists():
+        return dev_path
+    raise FileNotFoundError("minimal.yaml not found. Run `pip install -e .` first.")
+
+
+def run(args) -> int:
+    vault = args.path.expanduser().resolve()
+    vault.mkdir(parents=True, exist_ok=True)
+
+    for layer in _LAYER_DIRS:
+        (vault / layer).mkdir(exist_ok=True)
+
+    config_path = vault / "brainkeeper.yaml"
+    if config_path.exists():
+        print(
+            f"warning: {config_path} already exists - skipping. "
+            "Edit it manually to change your vault configuration.",
+            file=sys.stderr,
+        )
+    else:
+        minimal = _find_minimal_yaml()
+        config_path.write_text(minimal.read_text(encoding="utf-8"), encoding="utf-8")
+        print(f"created vault at {vault}")
+
+    return 0

brainkeeper/cli/serve.py

@@ -0,0 +1,22 @@
+"""MCP serve subcommand."""
+
+from __future__ import annotations
+import logging
+import sys
+
+from ..mcp.server import BrainkeeperServer
+
+
+def run(args) -> int:
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+    vault = args.vault.expanduser().resolve()
+    if not vault.is_dir():
+        print(f"error: vault path is not a directory: {vault}", file=sys.stderr)
+        return 1
+    srv = BrainkeeperServer(vault)
+    srv.run_stdio()
+    return 0

brainkeeper/core/config.py

@@ -0,0 +1,104 @@
+"""Load and validate brainkeeper.yaml against the JSON Schema."""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+from pydantic import BaseModel, Field
+
+
+def _find_schema() -> Path:
+    # Path inside an installed wheel (where force-include populated brainkeeper/spec/)
+    via_package = Path(
+        str(
+            importlib.resources.files("brainkeeper.spec")
+            / "schema"
+            / "brainkeeper.schema.json"
+        )
+    )
+    if via_package.exists():
+        return via_package
+    # Dev fallback: src/brainkeeper/core/config.py walks up to repo root
+    # parents: [0]=core/, [1]=brainkeeper/, [2]=src/, [3]=repo root
+    dev_path = (
+        Path(__file__).resolve().parents[3]
+        / "spec"
+        / "schema"
+        / "brainkeeper.schema.json"
+    )
+    if dev_path.exists():
+        return dev_path
+    raise FileNotFoundError(
+        "brainkeeper.schema.json not found. "
+        "Run `pip install -e .` or build the wheel first."
+    )
+
+
+_SCHEMA_PATH = _find_schema()
+
+
+class LayerOptions(BaseModel):
+    path: str
+    format: str | None = None
+    status_field: str | None = None
+    active_values: list[str] | None = None
+    year_subfolder: bool | None = None
+
+
+def _coerce_layer(value: Any) -> LayerOptions:
+    if isinstance(value, str):
+        return LayerOptions(path=value)
+    if isinstance(value, dict):
+        return LayerOptions(**value)
+    raise ValueError(f"layer entry must be str or dict: {value!r}")
+
+
+class Layers(BaseModel):
+    inbox: LayerOptions
+    journal: LayerOptions
+    projects: LayerOptions
+    areas: LayerOptions
+    brain: LayerOptions
+    archive: LayerOptions
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> "Layers":
+        return cls(**{k: _coerce_layer(v) for k, v in raw.items()})
+
+
+class Config(BaseModel):
+    layers: Layers
+    capture_routing: dict[str, str]
+    vault_root: Path = Field(exclude=True)
+
+    def layer_path(self, key: str) -> Path:
+        opts: LayerOptions = getattr(self.layers, key)
+        return self.vault_root / opts.path
+
+
+class ConfigLoader:
+    """Loads brainkeeper.yaml from a vault root and validates against schema."""
+
+    def __init__(self, vault_root: Path) -> None:
+        self.vault_root = Path(vault_root)
+        self._validator = Draft202012Validator(json.loads(_SCHEMA_PATH.read_text()))
+
+    def load(self) -> Config:
+        path = self.vault_root / "brainkeeper.yaml"
+        if not path.exists():
+            raise FileNotFoundError(f"no brainkeeper.yaml at {self.vault_root}")
+        raw = yaml.safe_load(path.read_text()) or {}
+        errors = sorted(self._validator.iter_errors(raw), key=lambda e: e.path)
+        if errors:
+            msg = "; ".join(e.message for e in errors)
+            raise ValueError(f"brainkeeper.yaml fails schema: {msg}")
+        return Config(
+            layers=Layers.from_raw(raw["layers"]),
+            capture_routing=raw["capture_routing"],
+            vault_root=self.vault_root,
+        )

brainkeeper/core/frontmatter.py

@@ -0,0 +1,72 @@
+"""YAML frontmatter parsing + validation against brainkeeper spec v0.1.3."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from pathlib import Path
+from typing import Any
+
+import frontmatter
+
+REQUIRED_FIELDS: tuple[str, ...] = ("created", "updated", "tags")
+DATE_FIELDS: tuple[str, ...] = ("created", "updated")
+
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_TAG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$")
+
+
+class ValidationError(Exception):
+    """Raised when frontmatter fails spec validation."""
+
+
+class FrontmatterParser:
+    """Thin wrapper over python-frontmatter with spec validation."""
+
+    def parse(self, path: Path) -> tuple[dict[str, Any], str]:
+        post = frontmatter.load(path)
+        meta = dict(post.metadata or {})
+        # PyYAML auto-coerces ISO dates into date/datetime objects.
+        # Normalize known date fields back to YYYY-MM-DD strings so downstream
+        # consumers and the spec-aligned validator see consistent string types.
+        for field in DATE_FIELDS:
+            v = meta.get(field)
+            if isinstance(v, (_dt.date, _dt.datetime)):
+                meta[field] = v.isoformat()[:10]
+        return meta, post.content
+
+    def validate(self, meta: dict[str, Any]) -> list[str]:
+        errors: list[str] = []
+
+        for field in REQUIRED_FIELDS:
+            value = meta.get(field)
+            if value in (None, "", []):
+                errors.append(f"required field `{field}` is missing or empty")
+
+        for field in DATE_FIELDS:
+            v = meta.get(field)
+            if v in (None, "", False):
+                continue
+            if not _DATE_RE.match(str(v)):
+                errors.append(f"`{field}` value '{v}' is not YYYY-MM-DD")
+
+        created = meta.get("created")
+        updated = meta.get("updated")
+        if (
+            isinstance(created, str)
+            and isinstance(updated, str)
+            and _DATE_RE.match(created)
+            and _DATE_RE.match(updated)
+            and updated < created
+        ):
+            errors.append(
+                f"`updated` ({updated}) is earlier than `created` ({created})"
+            )
+
+        tags = meta.get("tags")
+        if isinstance(tags, list):
+            for t in tags:
+                if not isinstance(t, str) or not _TAG_RE.match(t.lstrip("#")):
+                    errors.append(f"tag '{t}' fails grammar")
+
+        return errors

brainkeeper/core/fs.py

@@ -0,0 +1,47 @@
+"""Atomic file writes with optional mtime check."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+class StaleWriteError(Exception):
+    """Raised when expected_mtime does not match the file's current mtime."""
+
+
+class AtomicWriter:
+    """tmp-file + os.replace for crash-safe writes."""
+
+    def write_atomic(
+        self,
+        path: Path,
+        content: str,
+        expected_mtime: float | None = None,
+    ) -> float:
+        path = Path(path)
+        if expected_mtime is not None and path.exists():
+            actual = path.stat().st_mtime
+            if abs(actual - expected_mtime) > 1e-6:
+                raise StaleWriteError(
+                    f"expected mtime {expected_mtime} but found {actual} for {path}"
+                )
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_path = tempfile.mkstemp(
+            prefix=path.name + ".",
+            suffix=".tmp",
+            dir=path.parent,
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fp:
+                fp.write(content)
+            os.replace(tmp_path, path)
+        except Exception:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
+        return path.stat().st_mtime

brainkeeper/core/index.py

@@ -0,0 +1,104 @@
+"""In-memory index of vault notes with frontmatter metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from threading import RLock
+from typing import Any
+
+from .frontmatter import FrontmatterParser
+
+
+@dataclass
+class NoteMeta:
+    path: Path
+    frontmatter: dict[str, Any]
+    mtime: float
+    validation_errors: list[str]
+
+
+class Index:
+    """Thread-safe dict[Path, NoteMeta] with simple queries."""
+
+    def __init__(self, vault_root: Path) -> None:
+        self.vault_root = Path(vault_root)
+        self._lock = RLock()
+        self._notes: dict[Path, NoteMeta] = {}
+        self._parser = FrontmatterParser()
+
+    def build(self) -> None:
+        with self._lock:
+            self._notes.clear()
+            for f in self.vault_root.rglob("*.md"):
+                parts = f.relative_to(self.vault_root).parts
+                if any(p.startswith(".") or p == "_templates" for p in parts):
+                    continue
+                self._index_file(f)
+
+    def update(self, path: Path) -> None:
+        path = Path(path)
+        with self._lock:
+            if not path.exists():
+                self._notes.pop(path, None)
+                return
+            self._index_file(path)
+
+    def remove(self, path: Path) -> None:
+        with self._lock:
+            self._notes.pop(Path(path), None)
+
+    def get(self, path: Path) -> NoteMeta | None:
+        with self._lock:
+            return self._notes.get(Path(path))
+
+    def paths(self) -> list[Path]:
+        with self._lock:
+            return list(self._notes.keys())
+
+    def by_tag(self, tag: str) -> list[NoteMeta]:
+        with self._lock:
+            return [
+                m
+                for m in self._notes.values()
+                if isinstance(m.frontmatter.get("tags"), list)
+                and tag in m.frontmatter["tags"]
+            ]
+
+    def by_status(self, status: str) -> list[NoteMeta]:
+        with self._lock:
+            return [
+                m
+                for m in self._notes.values()
+                if str(m.frontmatter.get("status")) == status
+            ]
+
+    def by_type(self, type_value: str) -> list[NoteMeta]:
+        with self._lock:
+            return [
+                m
+                for m in self._notes.values()
+                if str(m.frontmatter.get("type")) == type_value
+            ]
+
+    def orphans(self) -> list[NoteMeta]:
+        """Notes with any validation error against the spec."""
+        with self._lock:
+            return [m for m in self._notes.values() if m.validation_errors]
+
+    def _index_file(self, path: Path) -> None:
+        try:
+            meta, _ = self._parser.parse(path)
+        except Exception:
+            meta = {}
+        errors = self._parser.validate(meta)
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            return
+        self._notes[path] = NoteMeta(
+            path=path,
+            frontmatter=meta,
+            mtime=mtime,
+            validation_errors=errors,
+        )

brainkeeper/core/rescanner.py

@@ -0,0 +1,52 @@
+"""Periodic safety-net rescanner that walks the vault and reconciles Index."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+
+from .index import Index
+
+log = logging.getLogger(__name__)
+
+
+class PeriodicRescanner:
+    def __init__(
+        self, vault_root: Path, index: Index, interval_seconds: int = 300
+    ) -> None:
+        self.vault_root = Path(vault_root)
+        self.index = index
+        self.interval = interval_seconds
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=5)
+
+    def rescan_once(self) -> None:
+        on_disk: set[Path] = set()
+        for f in self.vault_root.rglob("*.md"):
+            parts = f.relative_to(self.vault_root).parts
+            if any(p.startswith(".") or p == "_templates" for p in parts):
+                continue
+            on_disk.add(f)
+            self.index.update(f)
+        in_index = set(self.index.paths())
+        for missing in in_index - on_disk:
+            log.info("rescan: removing missing file from index: %s", missing)
+            self.index.remove(missing)
+
+    def _loop(self) -> None:
+        while not self._stop.wait(self.interval):
+            try:
+                self.rescan_once()
+            except Exception:
+                log.exception("rescan iteration failed")

brainkeeper/core/watcher.py

@@ -0,0 +1,85 @@
+"""Filesystem watcher pushing updates into Index, debounced."""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+from .index import Index
+
+
+class _Handler(FileSystemEventHandler):
+    def __init__(self, vault_root: Path, index: Index, debounce_ms: int) -> None:
+        self.vault_root = vault_root
+        self.index = index
+        self.debounce = debounce_ms / 1000.0
+        self._timers: dict[Path, threading.Timer] = {}
+        self._lock = threading.Lock()
+
+    def _schedule(self, path: Path, deleted: bool) -> None:
+        if path.suffix != ".md":
+            return
+        try:
+            rel = path.relative_to(self.vault_root)
+        except ValueError:
+            return
+        if any(p.startswith(".") or p == "_templates" for p in rel.parts):
+            return
+
+        def _fire():
+            with self._lock:
+                self._timers.pop(path, None)
+            if deleted:
+                self.index.remove(path)
+            else:
+                self.index.update(path)
+
+        with self._lock:
+            t = self._timers.get(path)
+            if t:
+                t.cancel()
+            timer = threading.Timer(self.debounce, _fire)
+            timer.daemon = True
+            self._timers[path] = timer
+            timer.start()
+
+    def on_created(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            return
+        self._schedule(Path(event.src_path), deleted=False)
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            return
+        self._schedule(Path(event.src_path), deleted=False)
+
+    def on_deleted(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            return
+        self._schedule(Path(event.src_path), deleted=True)
+
+    def on_moved(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            return
+        self._schedule(Path(event.src_path), deleted=True)
+        self._schedule(Path(event.dest_path), deleted=False)
+
+
+class FileWatcher:
+    def __init__(self, vault_root: Path, index: Index, debounce_ms: int = 200) -> None:
+        self.vault_root = Path(vault_root)
+        self.index = index
+        self.debounce_ms = debounce_ms
+        self._observer = Observer()
+        self._handler = _Handler(self.vault_root, index, debounce_ms)
+
+    def start(self) -> None:
+        self._observer.schedule(self._handler, str(self.vault_root), recursive=True)
+        self._observer.start()
+
+    def stop(self) -> None:
+        self._observer.stop()
+        self._observer.join(timeout=5)