oyhub 0.2.0__tar.gz

oyhub-0.2.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: oyhub
+Version: 0.2.0
+Summary: Local agent harness: central skill library, Obsidian + SQLite FTS5 memory, background curator — served over MCP.
+Author-email: Akan Abdireshov <asanovich.02@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Asanovichoff/oyhub
+Project-URL: Repository, https://github.com/Asanovichoff/oyhub
+Project-URL: Issues, https://github.com/Asanovichoff/oyhub/issues
+Keywords: mcp,agent,memory,obsidian,claude,skills,harness
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# OyHub
+
+**A local, always-on agent harness that fixes skill sprawl and context exhaustion.**
+
+Engineers using AI assistants hit two walls: skills scattered across projects with nothing organized in one place, and context windows that fill up and forget everything between sessions. OyHub is an MCP server you install once on your machine — Claude Desktop, Claude Code, and Cursor connect to it and gain:
+
+- **One central skill library** with per-project activation. Skills live in `~/.oyhub/skills` (agentskills.io-compatible `SKILL.md` format). Activate a project and only its relevant skills appear — your Kubernetes skills stay out of your React sessions.
+- **Persistent memory that survives any context window.** Curated facts go to your **Obsidian vault** as plain markdown (human-readable, editable, graph-linked). Full conversation history goes to **SQLite + FTS5** — full-text searchable recall at zero LLM cost. Instead of context running out, the assistant *retrieves* the five messages that matter.
+- **Loop engineering in the background.** A curator loop runs on idle: archives stale skills (never deletes — archive is recoverable), dedupes memory entries, pins protect anything you care about, and every action is logged to a `Curator Log.md` note in your vault so the loop's work stays visible.
+- **Injection-scanned writes.** Memory and skills persist into every future session's context, so anything flowing into them is scanned at write time — instruction-override phrasing and credential-exfil link shapes are refused with a reason. Legitimate engineering content (curl commands, env var names) passes.
+- **Safe under concurrent clients.** Multiple assistants can run OyHub against the same state simultaneously: SQLite runs in WAL mode with busy timeouts, and all shared JSON/markdown writes go through file-locked atomic read-modify-write.
+- **CI/CD + Docker from day one.** GitHub Actions runs lint + tests on a 6-way OS/Python matrix, builds the Docker image, cuts a GitHub release on every version tag, and publishes to PyPI via trusted publishing.
+
+Zero runtime dependencies — Python stdlib only. No API key: the connected assistant is the intelligence; OyHub is the harness.
+
+## Install
+
+```bash
+git clone https://github.com/Asanovichoff/oyhub && cd oyhub
+python3 -m oyhub doctor   # health check
+```
+
+Set where memory lives (your existing Obsidian vault):
+
+```bash
+export OYHUB_VAULT=~/Documents/MyVault
+```
+
+### Connect Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "oyhub": {
+      "command": "python3",
+      "args": ["-m", "oyhub"],
+      "env": {
+        "PYTHONPATH": "/path/to/oyhub",
+        "OYHUB_VAULT": "/Users/you/Documents/MyVault"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Claude Desktop ignores a `cwd` field — `PYTHONPATH` is what makes
+> `python3 -m oyhub` importable. Alternatively, `pip3 install -e /path/to/oyhub`
+> once, then use `"command": "oyhub"` with no `args` or `PYTHONPATH`.
+
+### Connect Claude Code
+
+```bash
+claude mcp add oyhub --env PYTHONPATH=/path/to/oyhub --env OYHUB_VAULT=~/Documents/MyVault -- python3 -m oyhub
+```
+
+Or after `pip3 install -e /path/to/oyhub`: `claude mcp add oyhub -- oyhub`
+
+### Docker
+
+```bash
+docker compose run --rm oyhub          # stdio MCP server
+docker compose run --rm --entrypoint python oyhub -m oyhub doctor
+```
+
+## The tools it exposes
+
+| Tool | What it does |
+|---|---|
+| `project_activate` | Scope skills + memory to a project (creates profile if new) |
+| `skill_add` / `skill_view` / `skill_list` / `skill_search` | Central library; list shows the compact index (60-char descriptions), bodies load on demand |
+| `memory_add` / `memory_snapshot` | Curated memory in your Obsidian vault, project-scoped or global |
+| `session_log` / `session_search` / `session_recent` | FTS5-indexed history: log important turns, search them later with context windows |
+| `curator_run` / `curator_pin` | Run maintenance now; pin skills the curator must never touch |
+
+## A typical day
+
+1. Start a session: Claude calls `project_activate("webapp")` and `memory_snapshot` — it now knows your conventions and this project's facts, without you repeating them.
+2. Work normally. When something worth keeping comes up, Claude calls `memory_add` ("staging DB is read-only") or `skill_add` (a deploy procedure it just worked out).
+3. Next week, in a *fresh* session: "how did we fix that CORS issue?" → `session_search("CORS")` returns the exact exchange. Nothing was lost when the old context window died.
+4. Meanwhile the curator has deduped memory and archived skills untouched for 90 days — check `Curator Log.md` in Obsidian to see what it did.
+
+## Architecture
+
+```
+Claude / Cursor  ──MCP (stdio JSON-RPC)──►  oyhub/server.py
+                                              │
+                    ┌─────────────────────────┼─────────────────────┐
+                    ▼                         ▼                     ▼
+             skills.py                 memory.py               curator.py
+      central library + index    Obsidian vault (curated)   idle-triggered loop:
+      per-project activation     SQLite FTS5 (raw recall)   archive stale, dedupe,
+      usage tracking             frozen-snapshot reads      log actions to vault
+```
+
+Design lineage: the frozen-snapshot memory, 60-char skill index, archive-never-delete curator, and idle-triggered maintenance are patterns from [Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research, MIT), adapted for a keyless MCP harness.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check oyhub tests && pytest tests/ -q   # what CI runs
+```
+
+22 tests, all offline — including concurrency tests (parallel writers, no lost updates) and injection-guard tests. CI matrix: Ubuntu + macOS × Python 3.10–3.12, plus a Docker build + smoke test. Tag `v*` to cut a GitHub release and publish to PyPI (trusted publishing — configure once under PyPI → Publishing).
+
+## Roadmap
+
+- LLM-assisted curation (summarize/consolidate memory notes, improve skill descriptions)
+- Skill import from agentskills.io and Claude skill bundles
+- Session auto-logging middleware
+- Vector search as an optional complement to FTS5
+
+MIT license.

oyhub-0.2.0/README.md

@@ -0,0 +1,115 @@
+# OyHub
+
+**A local, always-on agent harness that fixes skill sprawl and context exhaustion.**
+
+Engineers using AI assistants hit two walls: skills scattered across projects with nothing organized in one place, and context windows that fill up and forget everything between sessions. OyHub is an MCP server you install once on your machine — Claude Desktop, Claude Code, and Cursor connect to it and gain:
+
+- **One central skill library** with per-project activation. Skills live in `~/.oyhub/skills` (agentskills.io-compatible `SKILL.md` format). Activate a project and only its relevant skills appear — your Kubernetes skills stay out of your React sessions.
+- **Persistent memory that survives any context window.** Curated facts go to your **Obsidian vault** as plain markdown (human-readable, editable, graph-linked). Full conversation history goes to **SQLite + FTS5** — full-text searchable recall at zero LLM cost. Instead of context running out, the assistant *retrieves* the five messages that matter.
+- **Loop engineering in the background.** A curator loop runs on idle: archives stale skills (never deletes — archive is recoverable), dedupes memory entries, pins protect anything you care about, and every action is logged to a `Curator Log.md` note in your vault so the loop's work stays visible.
+- **Injection-scanned writes.** Memory and skills persist into every future session's context, so anything flowing into them is scanned at write time — instruction-override phrasing and credential-exfil link shapes are refused with a reason. Legitimate engineering content (curl commands, env var names) passes.
+- **Safe under concurrent clients.** Multiple assistants can run OyHub against the same state simultaneously: SQLite runs in WAL mode with busy timeouts, and all shared JSON/markdown writes go through file-locked atomic read-modify-write.
+- **CI/CD + Docker from day one.** GitHub Actions runs lint + tests on a 6-way OS/Python matrix, builds the Docker image, cuts a GitHub release on every version tag, and publishes to PyPI via trusted publishing.
+
+Zero runtime dependencies — Python stdlib only. No API key: the connected assistant is the intelligence; OyHub is the harness.
+
+## Install
+
+```bash
+git clone https://github.com/Asanovichoff/oyhub && cd oyhub
+python3 -m oyhub doctor   # health check
+```
+
+Set where memory lives (your existing Obsidian vault):
+
+```bash
+export OYHUB_VAULT=~/Documents/MyVault
+```
+
+### Connect Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "oyhub": {
+      "command": "python3",
+      "args": ["-m", "oyhub"],
+      "env": {
+        "PYTHONPATH": "/path/to/oyhub",
+        "OYHUB_VAULT": "/Users/you/Documents/MyVault"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Claude Desktop ignores a `cwd` field — `PYTHONPATH` is what makes
+> `python3 -m oyhub` importable. Alternatively, `pip3 install -e /path/to/oyhub`
+> once, then use `"command": "oyhub"` with no `args` or `PYTHONPATH`.
+
+### Connect Claude Code
+
+```bash
+claude mcp add oyhub --env PYTHONPATH=/path/to/oyhub --env OYHUB_VAULT=~/Documents/MyVault -- python3 -m oyhub
+```
+
+Or after `pip3 install -e /path/to/oyhub`: `claude mcp add oyhub -- oyhub`
+
+### Docker
+
+```bash
+docker compose run --rm oyhub          # stdio MCP server
+docker compose run --rm --entrypoint python oyhub -m oyhub doctor
+```
+
+## The tools it exposes
+
+| Tool | What it does |
+|---|---|
+| `project_activate` | Scope skills + memory to a project (creates profile if new) |
+| `skill_add` / `skill_view` / `skill_list` / `skill_search` | Central library; list shows the compact index (60-char descriptions), bodies load on demand |
+| `memory_add` / `memory_snapshot` | Curated memory in your Obsidian vault, project-scoped or global |
+| `session_log` / `session_search` / `session_recent` | FTS5-indexed history: log important turns, search them later with context windows |
+| `curator_run` / `curator_pin` | Run maintenance now; pin skills the curator must never touch |
+
+## A typical day
+
+1. Start a session: Claude calls `project_activate("webapp")` and `memory_snapshot` — it now knows your conventions and this project's facts, without you repeating them.
+2. Work normally. When something worth keeping comes up, Claude calls `memory_add` ("staging DB is read-only") or `skill_add` (a deploy procedure it just worked out).
+3. Next week, in a *fresh* session: "how did we fix that CORS issue?" → `session_search("CORS")` returns the exact exchange. Nothing was lost when the old context window died.
+4. Meanwhile the curator has deduped memory and archived skills untouched for 90 days — check `Curator Log.md` in Obsidian to see what it did.
+
+## Architecture
+
+```
+Claude / Cursor  ──MCP (stdio JSON-RPC)──►  oyhub/server.py
+                                              │
+                    ┌─────────────────────────┼─────────────────────┐
+                    ▼                         ▼                     ▼
+             skills.py                 memory.py               curator.py
+      central library + index    Obsidian vault (curated)   idle-triggered loop:
+      per-project activation     SQLite FTS5 (raw recall)   archive stale, dedupe,
+      usage tracking             frozen-snapshot reads      log actions to vault
+```
+
+Design lineage: the frozen-snapshot memory, 60-char skill index, archive-never-delete curator, and idle-triggered maintenance are patterns from [Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research, MIT), adapted for a keyless MCP harness.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check oyhub tests && pytest tests/ -q   # what CI runs
+```
+
+22 tests, all offline — including concurrency tests (parallel writers, no lost updates) and injection-guard tests. CI matrix: Ubuntu + macOS × Python 3.10–3.12, plus a Docker build + smoke test. Tag `v*` to cut a GitHub release and publish to PyPI (trusted publishing — configure once under PyPI → Publishing).
+
+## Roadmap
+
+- LLM-assisted curation (summarize/consolidate memory notes, improve skill descriptions)
+- Skill import from agentskills.io and Claude skill bundles
+- Session auto-logging middleware
+- Vector search as an optional complement to FTS5
+
+MIT license.

oyhub-0.2.0/oyhub/__init__.py

@@ -0,0 +1,12 @@
+"""OyHub — a local, always-on agent harness for engineers.
+
+One central skill library with per-project activation, persistent memory
+(Obsidian vault + SQLite FTS5 recall), and a background curator loop —
+exposed to Claude Desktop / Claude Code / Cursor as an MCP server.
+
+Fixes two problems:
+  1. Skill sprawl  — skills scattered across projects, nothing organized.
+  2. Context exhaustion — knowledge lost when the context window fills up.
+"""
+
+__version__ = "0.2.0"

oyhub-0.2.0/oyhub/__main__.py

@@ -0,0 +1,35 @@
+"""CLI: `python -m oyhub` runs the MCP server (stdio).
+`python -m oyhub doctor` prints a health check."""
+
+from __future__ import annotations
+
+import sys
+
+from .config import HubConfig
+from .server import Hub, serve
+
+
+def doctor() -> int:
+    cfg = HubConfig()
+    cfg.ensure_dirs()
+    hub = Hub(cfg)
+    print(f"oyhub home : {cfg.home}")
+    print(f"vault         : {cfg.vault_path}")
+    print(f"skills        : {len(hub.skills.all_names())}")
+    print(f"projects      : {', '.join(hub.skills.list_projects()) or '(none)'}")
+    print(f"sessions db   : {cfg.db_path} "
+          f"({'exists' if cfg.db_path.exists() else 'will be created'})")
+    print(f"curator due   : {hub.curator.due()}")
+    print("status        : ok")
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] == "doctor":
+        return doctor()
+    serve()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oyhub-0.2.0/oyhub/config.py

@@ -0,0 +1,58 @@
+"""OyHub configuration. Everything lives under ~/.oyhub by default;
+the Obsidian vault is wherever the user's vault already is."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _home() -> Path:
+    return Path(os.getenv("OYHUB_HOME", "~/.oyhub")).expanduser()
+
+
+@dataclass
+class HubConfig:
+    home: Path = field(default_factory=_home)
+    # Obsidian vault root (the folder Obsidian opens). Memory notes go into
+    # a "OyHub" subfolder there. If unset, falls back to ~/.oyhub/vault
+    # (still plain markdown — you can open it as a vault later).
+    vault_path: Path = field(
+        default_factory=lambda: Path(
+            os.getenv("OYHUB_VAULT", "")
+        ).expanduser()
+        if os.getenv("OYHUB_VAULT")
+        else _home() / "vault"
+    )
+    memory_folder: str = "OyHub"
+    # Curated-memory snapshot budget (chars, not tokens — model-independent).
+    snapshot_char_limit: int = 8000
+    # Curator policy.
+    curator_interval_hours: float = 6.0
+    skill_stale_days: int = 90
+
+    @property
+    def skills_dir(self) -> Path:
+        return self.home / "skills"
+
+    @property
+    def archive_dir(self) -> Path:
+        return self.home / "archive"
+
+    @property
+    def db_path(self) -> Path:
+        return self.home / "sessions.db"
+
+    @property
+    def projects_file(self) -> Path:
+        return self.home / "projects.json"
+
+    @property
+    def state_file(self) -> Path:
+        return self.home / "state.json"
+
+    def ensure_dirs(self) -> None:
+        for p in (self.home, self.skills_dir, self.archive_dir,
+                  self.vault_path / self.memory_folder):
+            p.mkdir(parents=True, exist_ok=True)

oyhub-0.2.0/oyhub/curator.py

@@ -0,0 +1,144 @@
+"""The curator — loop engineering in the background.
+
+Runs periodically (and on server idle) to keep the hub healthy without any
+LLM calls in the MVP — pure policy, borrowed from Hermes' curator invariants:
+
+  * NEVER deletes — stale skills are archived (recoverable).
+  * Pinned skills bypass all automation.
+  * Dedupes curated-memory bullets (case-insensitive).
+  * Records every action it takes in a curator log note in the vault,
+    so the loop's work is visible to the user.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import time
+from dataclasses import dataclass, field
+
+from .config import HubConfig
+from .locks import read_json, update_json
+from .memory import VaultMemory
+from .skills import SkillStore
+
+
+@dataclass
+class CuratorReport:
+    archived_skills: list[str] = field(default_factory=list)
+    deduped_notes: dict = field(default_factory=dict)  # note name -> removed count
+    ran_at: str = ""
+
+    def summary(self) -> str:
+        bits = []
+        if self.archived_skills:
+            bits.append(f"archived {len(self.archived_skills)} stale skill(s): "
+                        + ", ".join(self.archived_skills))
+        removed = sum(self.deduped_notes.values())
+        if removed:
+            bits.append(f"removed {removed} duplicate memory entr(ies)")
+        return "; ".join(bits) or "nothing to do — hub is healthy"
+
+
+class Curator:
+    def __init__(self, cfg: HubConfig, skills: SkillStore, vault: VaultMemory):
+        self.cfg = cfg
+        self.skills = skills
+        self.vault = vault
+
+    # -- scheduling ------------------------------------------------------------
+
+    def due(self) -> bool:
+        state = self._read_state()
+        last = state.get("curator_last_run", 0.0)
+        return time.time() - last >= self.cfg.curator_interval_hours * 3600
+
+    def maybe_run(self) -> CuratorReport | None:
+        return self.run() if self.due() else None
+
+    # -- the loop body -----------------------------------------------------------
+
+    def run(self) -> CuratorReport:
+        report = CuratorReport(ran_at=_dt.datetime.now().isoformat(" ", "minutes"))
+        report.archived_skills = self._archive_stale_skills()
+        report.deduped_notes = self._dedupe_memory_notes()
+        self._write_state()
+        self._log_to_vault(report)
+        return report
+
+    def pin(self, skill_name: str) -> None:
+        def _pin(state: dict) -> dict:
+            state["pinned"] = sorted(set(state.get("pinned", [])) | {skill_name})
+            return state
+
+        update_json(self.cfg.state_file, {}, _pin)
+
+    def pinned(self) -> set[str]:
+        return set(self._read_state().get("pinned", []))
+
+    # -- policies ---------------------------------------------------------------
+
+    def _archive_stale_skills(self) -> list[str]:
+        cutoff = time.time() - self.cfg.skill_stale_days * 86400
+        usage = self.skills.usage()
+        pinned = self.pinned()
+        archived = []
+        for name in self.skills.all_names():
+            if name in pinned:
+                continue
+            rec = usage.get(name)
+            if rec is None:
+                continue  # never used since tracking began — grace period
+            if rec.get("last_used", time.time()) < cutoff:
+                if self.skills.remove(name):  # remove() archives, never deletes
+                    archived.append(name)
+        return archived
+
+    def _dedupe_memory_notes(self) -> dict:
+        out: dict[str, int] = {}
+        for path in sorted(self.vault.dir.glob("*.md")):
+            if path.name.startswith("Curator"):
+                continue
+            lines = path.read_text(encoding="utf-8").splitlines()
+            seen: set[str] = set()
+            kept: list[str] = []
+            removed = 0
+            for line in lines:
+                key = _normalize_bullet(line)
+                if key and key in seen:
+                    removed += 1
+                    continue
+                if key:
+                    seen.add(key)
+                kept.append(line)
+            if removed:
+                path.write_text("\n".join(kept) + "\n", encoding="utf-8")
+                out[path.name] = removed
+        return out
+
+    # -- bookkeeping --------------------------------------------------------------
+
+    def _read_state(self) -> dict:
+        return read_json(self.cfg.state_file, {})
+
+    def _write_state(self) -> None:
+        def _stamp(state: dict) -> dict:
+            state["curator_last_run"] = time.time()
+            return state
+
+        update_json(self.cfg.state_file, {}, _stamp)
+
+    def _log_to_vault(self, report: CuratorReport) -> None:
+        path = self.vault.dir / "Curator Log.md"
+        with path.open("a", encoding="utf-8") as f:
+            f.write(f"- {report.ran_at}: {report.summary()}\n")
+
+
+def _normalize_bullet(line: str) -> str:
+    """Key for dedupe: bullet text, lowercased, date-stamp stripped."""
+    s = line.strip()
+    if not s.startswith("- "):
+        return ""
+    s = s[2:]
+    if s.endswith(")*") and "*(" in s:
+        s = s[: s.rfind("*(")]
+    return " ".join(s.lower().split())

oyhub-0.2.0/oyhub/guard.py

@@ -0,0 +1,52 @@
+"""Injection scanning for content that persists into future context windows.
+
+Memory entries and skills are re-injected into system prompts across every
+future session — a poisoned entry persists until explicitly removed. So
+anything flowing INTO those stores is scanned at write time (the Hermes
+``threat_patterns`` pattern: one source of truth, strictness proportional
+to persistence).
+
+Deliberately narrow: we block instruction-hijack phrasing and data-exfil
+link shapes, not legitimate engineering content. A skill body containing
+``curl`` or an API example must pass; "ignore all previous instructions"
+must not.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# (compiled pattern, human-readable reason)
+_THREATS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"\bignore\s+(?:all\s+|any\s+)?(?:previous|prior|above|earlier)\s+"
+                r"(?:instructions?|context|prompts?)", re.I),
+     "instruction-override phrasing ('ignore previous instructions')"),
+    (re.compile(r"\bdisregard\s+(?:all\s+|your\s+)?(?:previous|prior|system)\s+"
+                r"(?:instructions?|prompts?)", re.I),
+     "instruction-override phrasing ('disregard prior instructions')"),
+    (re.compile(r"\bforget\s+(?:everything|all)\s+(?:you\s+know|above|previous)", re.I),
+     "instruction-override phrasing ('forget everything above')"),
+    (re.compile(r"\byou\s+are\s+now\s+(?:in\s+)?(?:developer|dan|jailbreak|god)\s*mode\b", re.I),
+     "jailbreak-mode phrasing"),
+    (re.compile(r"<\s*/?\s*system\s*>", re.I),
+     "embedded <system> tag"),
+    (re.compile(r"\bnew\s+system\s+prompt\s*:", re.I),
+     "system-prompt replacement phrasing"),
+    (re.compile(r"\bdo\s+not\s+(?:tell|inform|alert)\s+the\s+user\b", re.I),
+     "concealment instruction ('do not tell the user')"),
+    # Markdown link/image whose URL smuggles secrets in query params —
+    # the classic exfil channel for content rendered in a client.
+    (re.compile(r"\]\(\s*https?://[^)\s]*[?&][^)\s]*"
+                r"(?:token|secret|key|password|credential|auth)[^)\s]*=", re.I),
+     "markdown link with credential-shaped query parameter (possible exfil)"),
+]
+
+
+def first_threat(content: str) -> Optional[str]:
+    """Return a human-readable reason if *content* matches a threat pattern,
+    else None. Callers refuse the write and surface the reason."""
+    for pattern, reason in _THREATS:
+        if pattern.search(content):
+            return reason
+    return None

oyhub-0.2.0/oyhub/locks.py

@@ -0,0 +1,70 @@
+"""Cross-process safety primitives.
+
+Multiple MCP clients (Claude Desktop, Claude Code, Cowork) each spawn their
+own OyHub process against the same on-disk state. Without locking, two
+processes doing read-modify-write on the same JSON file silently lose
+updates (last write wins). Every shared JSON file goes through
+:func:`update_json` — an exclusive-lock + atomic-replace critical section.
+
+POSIX uses ``fcntl.flock`` on a sidecar ``.lock`` file; on platforms without
+fcntl (Windows) we degrade to lock-free atomic replace, which still prevents
+torn files even if it can't prevent lost updates.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+try:
+    import fcntl
+except ImportError:  # Windows
+    fcntl = None  # type: ignore[assignment]
+
+
+@contextmanager
+def locked(path: Path) -> Iterator[None]:
+    """Exclusive cross-process lock scoped to *path* (sidecar lockfile)."""
+    lock_path = path.parent / (path.name + ".lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = open(lock_path, "a+")
+    try:
+        if fcntl is not None:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        try:
+            if fcntl is not None:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            handle.close()
+
+
+def read_json(path: Path, default: Any) -> Any:
+    if not path.exists():
+        return default
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return default
+
+
+def write_json_atomic(path: Path, data: Any) -> None:
+    """Write via temp file + os.replace — readers never see a torn file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.parent / (path.name + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def update_json(path: Path, default: Any,
+                fn: Callable[[Any], Any]) -> Any:
+    """Atomic read-modify-write under an exclusive lock."""
+    with locked(path):
+        data = read_json(path, default)
+        data = fn(data)
+        write_json_atomic(path, data)
+        return data