meridian-server 0.1.0.dev1__py3-none-any.whl

meridian/MERIDIAN.md

@@ -0,0 +1,79 @@
+# Meridian Session Instructions
+
+You are connected to Meridian — a shared project memory across AI coding sessions.
+Multiple sessions (Claude Code tabs, Cursor, Windsurf, etc.) can be coordinating
+on this project concurrently. Treat the Meridian state as the source of truth
+for "what has been decided, claimed, and shipped."
+
+## ALWAYS
+
+- **`log_task` after every meaningful action** so parallel sessions can see your work.
+  One line per task. Mark `status` honestly: `done`, `pending`, `failed`.
+- **`set_decision`** for architectural, irreversible, or surprising choices.
+  These appear in the decisions log (newest first) and persist across sessions.
+- **`generate_handoff`** when context is filling up (~80k tokens) or before you stop.
+  A clean handoff lets a fresh session resume without re-deriving everything.
+- **`claim_task`** before starting work on something a parallel session might pick up.
+  **`release_task`** if you bail — don't leave it claimed.
+- **`claim_file(session_id, file_path)`** before editing shared files when parallel
+  sessions are active. **`release_file(session_id, file_path)`** when done.
+  Use **`idle_until_session_done(watching_session_id)`** to wait before taking
+  over a file another session holds. Locks auto-expire after 2 hours. For a big
+  shared file, claim a single symbol instead so another session can edit a
+  different one: pass **`symbol`** (e.g. `"AuthRouter"` or `"AuthRouter.login"`)
+  **and `content`** (the file's full source) — Meridian parses it and blocks only
+  on an overlapping line range, telling you which symbols are still safe.
+- **After completing each sprint item**, call `get_sprint_progress(project_id,
+  session_id)` before claiming the next one. Its `board_change` field reports any
+  items a planner injected since this session started (also echoed on
+  `complete_sprint_item`/`claim_sprint_item`), so single-terminal runs pick up
+  mid-run additions at the item boundary without interrupting the current task.
+- **`update_md_section`** proposes a replacement for an anchored CLAUDE.md/AGENTS.md
+  section. Autonomous executor sessions leave it gated behind a dashboard HITL.
+  Human planning sessions (claude.ai) may pass **`force=true`** to skip the HITL and
+  apply the change directly — only use `force` when a human is driving the session.
+- **Mid-run corrections**: after each `complete_sprint_item`, call
+  `list_hitl_requests(status='pending')` and handle any request with
+  `kind='correction'` before the next item: apply the correction, `log_task` it,
+  and `answer_hitl(request_id, "acknowledged")`. Corrections never block an
+  unattended run — fail open, log, and keep going. (Plain `kind='question'`
+  requests stay blocking/auto-answerable as before.)
+
+## ON SESSION START
+
+Call `start_session(project_id, session_name)` once. That single call:
+- registers this session
+- returns the current goal (north star + version goal + sprint)
+- returns the last 10 tasks (ambient context)
+- returns the list of other active sessions
+- tells you whether a handoff file exists from a prior session
+
+If a handoff exists, read it before doing anything else.
+
+## ON SESSION END
+
+Before you stop, call `generate_handoff` so the next session can resume cleanly.
+Ensure any tasks you logged as `pending` are either completed or released.
+
+## DOCS FILES
+
+- **Never hand-write `docs/mcp-tools.md`** — it is auto-generated. Regenerate it
+  with `pixi run python -c "import asyncio; from meridian import server as srv; doc = asyncio.run(srv.mcp_tools_doc()); open('docs/mcp-tools.md','w').write(doc)"` whenever MCP tool definitions change.
+- **Never auto-write other `docs/*.md` files** unless the sprint item explicitly
+  says to update them. Executor sessions writing docs speculatively cause the docs
+  to go backwards (replacing current content with stale or hallucinated content).
+  If a docs update is needed, file it as a separate sprint item for human review.
+
+## DESIGN PRINCIPLES
+
+- The version goal is **stable** — only humans (or you when explicitly directed)
+  should change it. Auto-summaries and sprint changes do not bump it.
+- The sprint changes per cycle; the north star changes rarely.
+- Decisions are append-only — never edit prior entries. If a decision is reversed,
+  log a new decision describing the reversal.
+- Tasks are immutable once logged. If a task was wrong, log a corrective task.
+
+## OVERRIDE
+
+Drop a `MERIDIAN.md` file at your project root to replace these defaults.
+The project-root file wins over Meridian's built-in.

meridian/__init__.py

@@ -0,0 +1,3 @@
+"""Meridian — multi-session Claude coordinator."""
+
+__version__ = "0.1.0"

meridian/__main__.py

@@ -0,0 +1,137 @@
+"""Entrypoint for ``python -m meridian``.
+
+Default: run the FastAPI HTTP server on port 7878. Useful for local
+development, the demo script, and any HTTP client.
+
+With ``--mcp``: run the MCP stdio server. This is the mode you wire into
+Claude Desktop / Claude Code via an ``mcpServers`` config block, e.g.
+
+```json
+{
+  "mcpServers": {
+    "meridian": {
+      "command": "pixi",
+      "args": ["run", "python", "-m", "meridian", "--mcp"],
+      "cwd": "/absolute/path/to/meridian/repository"
+    }
+  }
+}
+```
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import signal
+import socket
+import subprocess
+import sys
+
+
+def _kill_port(port: int) -> None:
+    """Kill any process listening on the given port before starting."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        if s.connect_ex(("127.0.0.1", port)) != 0:
+            return  # port is free
+    if sys.platform == "win32":
+        result = subprocess.run(
+            f"netstat -ano | findstr :{port}",
+            shell=True, capture_output=True, text=True,
+        )
+        for line in result.stdout.splitlines():
+            parts = line.split()
+            if parts and parts[-1].isdigit():
+                pid = int(parts[-1])
+                try:
+                    os.kill(pid, signal.SIGTERM)
+                except OSError:
+                    pass
+                break
+    else:
+        result = subprocess.run(
+            ["lsof", "-ti", f":{port}"], capture_output=True, text=True
+        )
+        for pid_str in result.stdout.split():
+            if pid_str.isdigit():
+                try:
+                    os.kill(int(pid_str), signal.SIGTERM)
+                except OSError:
+                    pass
+
+# psycopg3 requires SelectorEventLoop on Windows (ProactorEventLoop not supported).
+# Must be set before any asyncio.run() or uvicorn.run() call.
+if sys.platform == "win32":
+    import selectors
+    # psycopg3 requires SelectorEventLoop — override Windows default ProactorEventLoop
+    asyncio.set_event_loop_policy(asyncio.DefaultEventLoopPolicy())
+    loop = asyncio.SelectorEventLoop(selectors.SelectSelector())
+    asyncio.set_event_loop(loop)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI dispatch: HTTP server by default, MCP stdio with ``--mcp``."""
+    parser = argparse.ArgumentParser(
+        prog="meridian",
+        description="Multi-session Claude coordinator.",
+    )
+    parser.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Run the MCP server over stdio (for Claude Desktop / Code).",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("MERIDIAN_HOST", "127.0.0.1"),
+        help="HTTP bind host (default 127.0.0.1, override with MERIDIAN_HOST).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("MERIDIAN_PORT", "7878")),
+        help="HTTP port (default 7878, override with MERIDIAN_PORT).",
+    )
+    args = parser.parse_args(argv)
+
+    if args.mcp:
+        from .server import build_mcp_server
+
+        _, run_stdio = build_mcp_server()
+        # On Windows asyncio.run() creates a new ProactorEventLoop, breaking psycopg3.
+        # Use the SelectorEventLoop we set at module scope instead.
+        loop = asyncio.get_event_loop()
+        loop.run_until_complete(run_stdio())
+        return 0
+
+    import uvicorn
+    import sys as _sys
+
+    _kill_port(args.port)
+
+    if _sys.platform == "win32":
+        # psycopg3 requires SelectorEventLoop. On Windows, asyncio.run()
+        # (used by uvicorn.run()) creates ProactorEventLoop by default.
+        # Bypass asyncio.run() entirely: run uvicorn.Server on our SelectorEventLoop.
+        config = uvicorn.Config(
+            "meridian.server:app",
+            host=args.host,
+            port=args.port,
+            reload=False,
+            loop="none",
+        )
+        server = uvicorn.Server(config)
+        loop = asyncio.get_event_loop()  # SelectorEventLoop set above in module scope
+        loop.run_until_complete(server.serve())
+    else:
+        uvicorn.run(
+            "meridian.server:app",
+            host=args.host,
+            port=args.port,
+            reload=False,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

meridian/__main__entry.py

@@ -0,0 +1,54 @@
+"""PyInstaller entry point for the Meridian desktop executable.
+
+When run as a frozen exe:
+- DB lives in ~/.meridian/meridian.db (NOT next to the exe)
+- Starts uvicorn on MERIDIAN_PORT (default 7700)
+- Opens the browser after a short delay
+- Blocks until killed
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+import threading
+import webbrowser
+from pathlib import Path
+
+
+def _set_frozen_defaults() -> None:
+    """Override default DB/data paths so they land in ~/.meridian, not next to the exe."""
+    if getattr(sys, "frozen", False):
+        home_dir = Path.home() / ".meridian"
+        home_dir.mkdir(parents=True, exist_ok=True)
+        os.environ.setdefault("MERIDIAN_DB", str(home_dir / "meridian.db"))
+        os.environ.setdefault("MERIDIAN_DATA_DIR", str(home_dir / "data"))
+
+
+def _open_browser(port: int, delay: float = 1.5) -> None:
+    """Open the dashboard in the default browser after a short delay.
+
+    Opens /dashboard (where the first-run setup wizard lives) rather than
+    the landing page so binary users go straight into the app.
+    """
+    def _open():
+        time.sleep(delay)
+        webbrowser.open(f"http://localhost:{port}/dashboard")
+    t = threading.Thread(target=_open, daemon=True)
+    t.start()
+
+
+def main() -> None:
+    """Start the Meridian server and open the dashboard."""
+    _set_frozen_defaults()
+
+    import uvicorn
+    from meridian.server import app
+
+    port = int(os.environ.get("MERIDIAN_PORT", 7700))
+    _open_browser(port)
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()