neruva-control 0.1.0__py3-none-any.whl

neruva_control/__init__.py

@@ -0,0 +1,22 @@
+"""Neruva Control -- the local daemon behind Neruva Cockpit.
+
+The browser at app.neruva.io connects to this daemon over a loopback
+WebSocket (localhost:7331) to spawn and tail Claude Code sessions on
+the user's machine. Every session's events are auto-recorded into the
+Neruva substrate so the agent has a brain that survives across runs.
+
+Install: ``pip install neruva-control && neruva-control-install``
+
+After install, open https://app.neruva.io/cockpit -- the install
+script prints a one-time URL with your machine's auth token.
+
+Public surface for library users (rare; most users only need the CLI):
+
+    from neruva_control import daemon  # FastAPI app
+    from neruva_control._sessions import SessionManager
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

neruva_control/_cli.py

@@ -0,0 +1,163 @@
+"""CLI entry-point for `neruva-control`.
+
+Subcommands:
+  start   -- run the daemon in the foreground (blocks). Used by the OS
+             service registration. Power users can run it manually.
+  stop    -- find a running daemon and SIGTERM it.
+  status  -- print health: token present? daemon listening? PID?
+  link    -- print the fragment URL again (for re-link or new browser).
+  serve   -- alias for start (matches `uvicorn` muscle memory).
+"""
+from __future__ import annotations
+
+import argparse
+import signal
+import socket
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from ._config import config_dir, cockpit_link_url, load_token, token_path
+
+
+PORT = 7331
+
+
+def _is_listening(host: str = "127.0.0.1", port: int = PORT, timeout: float = 0.5) -> bool:
+    """True if something is bound to host:port. Used by `status` and by
+    install's "is the service already up" check."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.settimeout(timeout)
+    try:
+        s.connect((host, port))
+        s.close()
+        return True
+    except OSError:
+        return False
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    from .daemon import serve
+    host = args.bind or "127.0.0.1"
+    port = args.port or PORT
+    if host != "127.0.0.1":
+        print(
+            f"[neruva-control] WARNING: binding on {host}:{port} -- this exposes the daemon\n"
+            f"  beyond loopback. The auth token is the only thing protecting the API.\n"
+            f"  Recommended for remote access: Tailscale Serve over loopback instead.\n",
+            file=sys.stderr,
+        )
+    serve(host=host, port=port)
+    return 0
+
+
+def _cmd_status(_args: argparse.Namespace) -> int:
+    has_token = token_path().exists()
+    listening = _is_listening()
+    print(f"neruva-control {__version__}")
+    print(f"  config dir : {config_dir()}")
+    print(f"  token      : {'present' if has_token else 'MISSING (run neruva-control-install)'}")
+    print(f"  daemon     : {'listening on 127.0.0.1:' + str(PORT) if listening else 'NOT running'}")
+    if has_token:
+        try:
+            token = load_token()
+            print(f"  link URL   : {cockpit_link_url(token)}")
+        except Exception:
+            pass
+    return 0 if (has_token and listening) else 1
+
+
+def _cmd_link(_args: argparse.Namespace) -> int:
+    try:
+        token = load_token()
+    except FileNotFoundError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    print()
+    print("Open this URL in your browser to link this machine to Cockpit:")
+    print()
+    print(f"  {cockpit_link_url(token)}")
+    print()
+    print("(Token will be stashed in your browser's localStorage; the URL")
+    print(" fragment is stripped after first load. Same machine, same browser.)")
+    return 0
+
+
+def _cmd_stop(_args: argparse.Namespace) -> int:
+    """Best-effort daemon stop. Reads PID from pidfile if present;
+    falls back to telling user to kill it themselves on weird OSes."""
+    pidfile = config_dir() / "control.pid"
+    if not pidfile.exists():
+        print("No pidfile -- daemon not started by neruva-control or already stopped.")
+        return 0 if not _is_listening() else 1
+    try:
+        pid = int(pidfile.read_text().strip())
+    except Exception:
+        print(f"Bad pidfile at {pidfile}; remove it manually.", file=sys.stderr)
+        return 1
+    try:
+        if sys.platform == "win32":
+            import ctypes
+            PROCESS_TERMINATE = 1
+            handle = ctypes.windll.kernel32.OpenProcess(PROCESS_TERMINATE, False, pid)
+            if handle:
+                ctypes.windll.kernel32.TerminateProcess(handle, 0)
+                ctypes.windll.kernel32.CloseHandle(handle)
+        else:
+            import os as _os
+            _os.kill(pid, signal.SIGTERM)
+        # Wait briefly for socket to free
+        for _ in range(20):
+            if not _is_listening():
+                break
+            time.sleep(0.1)
+        try: pidfile.unlink()
+        except Exception: pass
+        print(f"Stopped daemon (pid {pid}).")
+        return 0
+    except ProcessLookupError:
+        print("Daemon process already gone.")
+        try: pidfile.unlink()
+        except Exception: pass
+        return 0
+    except Exception as e:
+        print(f"Failed to stop pid {pid}: {e}", file=sys.stderr)
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="neruva-control",
+        description="Local controller daemon for Neruva Cockpit.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_start = sub.add_parser("start", help="Run the daemon (foreground; blocks).")
+    p_start.add_argument("--bind", default=None,
+                         help="Bind address (default 127.0.0.1, loopback only). Pass "
+                              "0.0.0.0 to expose on LAN -- only do this if you trust "
+                              "your network. For remote access prefer Tailscale Serve.")
+    p_start.add_argument("--port", type=int, default=None, help=f"Port (default {PORT})")
+    p_serve = sub.add_parser("serve", help="Alias for start.")
+    p_serve.add_argument("--bind", default=None)
+    p_serve.add_argument("--port", type=int, default=None)
+    sub.add_parser("status", help="Show install + daemon status.")
+    sub.add_parser("link", help="Print the browser link URL.")
+    sub.add_parser("stop", help="Stop the daemon.")
+    args = parser.parse_args(argv)
+    handler = {
+        "start": _cmd_start,
+        "serve": _cmd_start,
+        "status": _cmd_status,
+        "link": _cmd_link,
+        "stop": _cmd_stop,
+    }.get(args.cmd)
+    if not handler:
+        parser.print_help()
+        return 2
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

neruva_control/_config.py

@@ -0,0 +1,85 @@
+"""Config + token I/O for neruva-control.
+
+Single source of truth for where files live (cross-platform via
+platformdirs). The token is the shared secret between the daemon
+process and the browser at app.neruva.io -- generated once at
+install, never rotated unless the user explicitly re-installs.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+from pathlib import Path
+from platformdirs import user_config_dir
+
+
+CONFIG_APP = "neruva"
+CONFIG_AUTHOR = "neruva"
+
+# Default substrate base. Overridable via NERUVA_API_BASE env (or future
+# control.toml setting) for self-hosted / staging.
+DEFAULT_API_BASE = "https://api.neruva.io"
+
+
+def neruva_api_base() -> str:
+    return os.environ.get("NERUVA_API_BASE", DEFAULT_API_BASE)
+
+
+def neruva_api_key() -> str | None:
+    """User's Neruva API key for posting recorded events. Read from env
+    first, then ~/.config/neruva/api.key as a stable per-machine option.
+    Returns None if unset -- daemon then runs in 'no-record' mode."""
+    k = os.environ.get("NERUVA_API_KEY")
+    if k:
+        return k.strip()
+    p = config_dir() / "api.key"
+    if p.exists():
+        try:
+            return p.read_text(encoding="utf-8").strip() or None
+        except Exception:
+            return None
+    return None
+
+
+def config_dir() -> Path:
+    p = Path(user_config_dir(CONFIG_APP, CONFIG_AUTHOR))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def token_path() -> Path:
+    return config_dir() / "control.token"
+
+
+def config_path() -> Path:
+    return config_dir() / "control.toml"
+
+
+def load_token() -> str:
+    """Read the shared token. Raises FileNotFoundError if not installed."""
+    p = token_path()
+    if not p.exists():
+        raise FileNotFoundError(
+            f"No token at {p}. Run `neruva-control-install` first."
+        )
+    return p.read_text(encoding="utf-8").strip()
+
+
+def write_token(token: str) -> Path:
+    """Write a new token (overwrite). Returns the path."""
+    p = token_path()
+    p.write_text(token, encoding="utf-8")
+    # chmod 600 on Unix; on Windows ACLs already restrict to user
+    if os.name == "posix":
+        os.chmod(p, 0o600)
+    return p
+
+
+def gen_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def cockpit_link_url(token: str, base: str = "https://app.neruva.io") -> str:
+    """Fragment URL the installer prints. Browser reads #token=..., stashes
+    in localStorage, then strips via history.replaceState."""
+    return f"{base}/cockpit#token={token}"

neruva_control/_install.py

@@ -0,0 +1,243 @@
+"""`neruva-control-install` -- the one-shot install command.
+
+Goals (Kyle: "make sure UX is world class"):
+  - User runs `pip install neruva-control && neruva-control-install`
+  - We generate a token, write config, register an OS service, start
+    the daemon, and print a clickable URL with the token in the
+    fragment so the browser can link in one click.
+  - No flags needed in the common path. `--help` documents the rare
+    overrides (--no-service, --reinstall, --port).
+
+Cross-platform service registration:
+  - macOS  : ~/Library/LaunchAgents/io.neruva.control.plist + launchctl load
+  - Linux  : ~/.config/systemd/user/neruva-control.service + systemctl --user
+  - Windows: schtasks /Create with ONLOGON trigger + immediate start
+
+If service registration fails (rootless containers, weird init systems),
+we degrade to "you're set up, but you'll need to run `neruva-control
+start` yourself in a background shell".
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import textwrap
+import time
+from pathlib import Path
+
+from ._config import config_dir, gen_token, write_token, cockpit_link_url, token_path
+
+
+PORT = 7331
+
+
+# ---------------------------------------------------------------------------
+# Cross-platform service registration
+# ---------------------------------------------------------------------------
+
+def _python_exe() -> str:
+    return sys.executable or "python"
+
+
+def _start_cmd() -> list[str]:
+    """The command that runs the daemon foreground. Used by service
+    registration on every OS."""
+    return [_python_exe(), "-m", "neruva_control._cli", "start"]
+
+
+def _install_macos() -> tuple[bool, str]:
+    label = "io.neruva.control"
+    plist_dir = Path.home() / "Library" / "LaunchAgents"
+    plist_dir.mkdir(parents=True, exist_ok=True)
+    plist = plist_dir / f"{label}.plist"
+    cmd_args = "".join(f"        <string>{a}</string>\n" for a in _start_cmd())
+    plist.write_text(textwrap.dedent(f"""\
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+          "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>Label</key><string>{label}</string>
+          <key>ProgramArguments</key>
+          <array>
+{cmd_args}        </array>
+          <key>RunAtLoad</key><true/>
+          <key>KeepAlive</key><true/>
+          <key>StandardOutPath</key>
+          <string>{config_dir()}/daemon.log</string>
+          <key>StandardErrorPath</key>
+          <string>{config_dir()}/daemon.err</string>
+        </dict>
+        </plist>
+    """), encoding="utf-8")
+    try:
+        # Unload first in case we're re-installing
+        subprocess.run(["launchctl", "unload", str(plist)], capture_output=True)
+        subprocess.run(["launchctl", "load", str(plist)], check=True, capture_output=True)
+        return True, f"launchd: loaded {plist}"
+    except Exception as e:
+        return False, f"launchctl load failed: {e}"
+
+
+def _install_linux() -> tuple[bool, str]:
+    unit_dir = Path.home() / ".config" / "systemd" / "user"
+    unit_dir.mkdir(parents=True, exist_ok=True)
+    unit = unit_dir / "neruva-control.service"
+    exec_line = " ".join(_start_cmd())
+    unit.write_text(textwrap.dedent(f"""\
+        [Unit]
+        Description=Neruva Control daemon (Cockpit local controller)
+        After=network.target
+
+        [Service]
+        ExecStart={exec_line}
+        Restart=always
+        RestartSec=3
+        Environment=PYTHONUNBUFFERED=1
+
+        [Install]
+        WantedBy=default.target
+    """), encoding="utf-8")
+    if not shutil.which("systemctl"):
+        return False, "systemctl not found; skip auto-service. Run `neruva-control start` manually."
+    try:
+        subprocess.run(["systemctl", "--user", "daemon-reload"], check=True, capture_output=True)
+        subprocess.run(["systemctl", "--user", "enable", "--now", "neruva-control.service"],
+                       check=True, capture_output=True)
+        return True, f"systemd-user: enabled {unit}"
+    except Exception as e:
+        return False, f"systemctl --user enable failed: {e}"
+
+
+def _install_windows() -> tuple[bool, str]:
+    """Use schtasks to register an ONLOGON task. Avoids needing admin."""
+    task_name = "NeruvaControl"
+    cmd_str = " ".join(f'"{a}"' for a in _start_cmd())
+    try:
+        # Delete any prior task silently
+        subprocess.run(["schtasks", "/Delete", "/TN", task_name, "/F"],
+                       capture_output=True)
+        # Create on-logon task that runs in current session
+        subprocess.run([
+            "schtasks", "/Create", "/TN", task_name,
+            "/SC", "ONLOGON",
+            "/TR", cmd_str,
+            "/RL", "LIMITED",
+            "/F",
+        ], check=True, capture_output=True)
+        # Run it now so user doesn't need to log out
+        subprocess.run(["schtasks", "/Run", "/TN", task_name],
+                       check=True, capture_output=True)
+        return True, f"Task Scheduler: registered task '{task_name}'"
+    except FileNotFoundError:
+        return False, "schtasks not on PATH; skipping auto-service"
+    except subprocess.CalledProcessError as e:
+        msg = (e.stderr or b"").decode(errors="replace").strip()
+        return False, f"schtasks /Create failed: {msg or e}"
+
+
+def _install_service() -> tuple[bool, str]:
+    if sys.platform == "darwin":
+        return _install_macos()
+    if sys.platform == "win32":
+        return _install_windows()
+    if sys.platform.startswith("linux"):
+        return _install_linux()
+    return False, f"unsupported platform: {sys.platform}"
+
+
+def _wait_for_daemon(timeout: float = 10.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(0.4)
+        try:
+            s.connect(("127.0.0.1", PORT))
+            s.close()
+            return True
+        except OSError:
+            time.sleep(0.3)
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="neruva-control-install",
+        description=(
+            "One-shot install for the Neruva Control daemon. "
+            "Generates a token, registers a background service, and "
+            "prints a one-time URL to link your browser to Cockpit."
+        ),
+    )
+    p.add_argument("--no-service", action="store_true",
+                   help="Skip OS service registration (run `neruva-control start` yourself).")
+    p.add_argument("--reinstall", action="store_true",
+                   help="Rotate the token even if one already exists.")
+    p.add_argument("--base", default="https://app.neruva.io",
+                   help="Cockpit base URL (default: https://app.neruva.io).")
+    args = p.parse_args(argv)
+
+    print()
+    print("Installing Neruva Control...")
+    print()
+
+    # 1. Token
+    if token_path().exists() and not args.reinstall:
+        from ._config import load_token
+        token = load_token()
+        print(f"  [skip] Token already present at {token_path()}")
+        print(f"         (re-run with --reinstall to rotate it)")
+    else:
+        token = gen_token()
+        write_token(token)
+        print(f"  [ok]   Token written to {token_path()}")
+
+    # 2. Service registration
+    if args.no_service:
+        print("  [skip] Service registration (--no-service set)")
+        service_msg = "skipped"
+        service_ok = False
+    else:
+        service_ok, service_msg = _install_service()
+        marker = "[ok]" if service_ok else "[warn]"
+        print(f"  {marker} {service_msg}")
+
+    # 3. Wait for daemon to come up (if we just registered + started one)
+    if service_ok:
+        up = _wait_for_daemon()
+        if up:
+            print(f"  [ok]   Daemon listening on 127.0.0.1:{PORT}")
+        else:
+            print(f"  [warn] Daemon didn't come up within 10s; check logs at {config_dir()}/daemon.log")
+    else:
+        print()
+        print(f"  Auto-service didn't register. Start the daemon manually with:")
+        print(f"    neruva-control start")
+        print(f"  (then re-run this command, or run `neruva-control link`)")
+
+    # 4. Print the fragment URL
+    print()
+    print("=" * 70)
+    print()
+    print("Open this URL in your browser to link this machine:")
+    print()
+    print(f"  {cockpit_link_url(token, args.base)}")
+    print()
+    print("Same machine, same browser. Token is stashed in localStorage; the")
+    print("URL fragment is stripped after first load. Bookmark app.neruva.io/cockpit.")
+    print()
+    print("=" * 70)
+    print()
+    return 0 if service_ok or args.no_service else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

neruva_control/_projects.py

@@ -0,0 +1,167 @@
+"""Projects -- the unit of organization in Cockpit.
+
+A Project bundles:
+  - A name (also the records substrate namespace)
+  - A working directory on disk (the cwd for spawned sessions)
+  - A list of sessions (active + recent)
+  - A list of "pinned" files the user has attached to context
+
+Persisted at ``~/.config/neruva/projects.json``. Single-user single-
+machine for v1; multi-machine sync is post-v1 (decision 23238 #11).
+
+Default project: created lazily on first session spawn if none exist.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import threading
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from ._config import config_dir
+
+
+_LOCK = threading.Lock()
+
+
+@dataclass
+class Project:
+    id: str
+    name: str
+    path: str  # absolute working directory
+    created_at_ms: int
+    last_active_ms: Optional[int] = None
+    pinned_files: list[str] = field(default_factory=list)  # paths relative to project path
+
+    @property
+    def namespace(self) -> str:
+        """Records-substrate namespace. Slug of name; safe for URLs."""
+        s = re.sub(r"[^a-z0-9_-]+", "-", self.name.lower()).strip("-")
+        return s or self.id
+
+
+def _projects_path() -> Path:
+    return config_dir() / "projects.json"
+
+
+def load_all() -> list[Project]:
+    p = _projects_path()
+    if not p.exists():
+        return []
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return [Project(**d) for d in data.get("projects", [])]
+    except Exception:
+        return []
+
+
+def save_all(projects: list[Project]) -> None:
+    p = _projects_path()
+    p.write_text(
+        json.dumps({"projects": [asdict(pr) for pr in projects]}, indent=2),
+        encoding="utf-8",
+    )
+    if os.name == "posix":
+        os.chmod(p, 0o600)
+
+
+def get(project_id: str) -> Optional[Project]:
+    for pr in load_all():
+        if pr.id == project_id:
+            return pr
+    return None
+
+
+def get_by_name(name: str) -> Optional[Project]:
+    for pr in load_all():
+        if pr.name == name:
+            return pr
+    return None
+
+
+def create(name: str, path: Optional[str] = None) -> Project:
+    """Create a new project. Path defaults to ~/.neruva/<name>/ which is
+    auto-created. If user passes a real existing dir, we use it as-is."""
+    with _LOCK:
+        all_p = load_all()
+        if any(p.name == name for p in all_p):
+            raise ValueError(f"project '{name}' already exists")
+        if not path:
+            base = Path.home() / ".neruva" / "projects" / re.sub(r"[^a-zA-Z0-9_-]+", "-", name)
+            base.mkdir(parents=True, exist_ok=True)
+            path = str(base.resolve())
+        else:
+            p = Path(path).expanduser().resolve()
+            if not p.exists():
+                p.mkdir(parents=True, exist_ok=True)
+            path = str(p)
+        proj = Project(
+            id="p_" + secrets.token_hex(6),
+            name=name,
+            path=path,
+            created_at_ms=int(time.time() * 1000),
+        )
+        all_p.append(proj)
+        save_all(all_p)
+        return proj
+
+
+def delete(project_id: str) -> bool:
+    """Remove project entry (does NOT delete files on disk)."""
+    with _LOCK:
+        all_p = load_all()
+        before = len(all_p)
+        all_p = [p for p in all_p if p.id != project_id]
+        if len(all_p) == before:
+            return False
+        save_all(all_p)
+        return True
+
+
+def touch(project_id: str) -> None:
+    """Mark project as active (updates last_active_ms)."""
+    with _LOCK:
+        all_p = load_all()
+        for p in all_p:
+            if p.id == project_id:
+                p.last_active_ms = int(time.time() * 1000)
+                save_all(all_p)
+                return
+
+
+def get_or_create_default() -> Project:
+    """Return an existing 'default' project or create one. Used when a
+    session is spawned without an explicit project."""
+    existing = get_by_name("default")
+    if existing:
+        return existing
+    return create("default")
+
+
+def pin_file(project_id: str, rel_path: str) -> Optional[Project]:
+    with _LOCK:
+        all_p = load_all()
+        for p in all_p:
+            if p.id == project_id:
+                if rel_path not in p.pinned_files:
+                    p.pinned_files.append(rel_path)
+                save_all(all_p)
+                return p
+    return None
+
+
+def unpin_file(project_id: str, rel_path: str) -> Optional[Project]:
+    with _LOCK:
+        all_p = load_all()
+        for p in all_p:
+            if p.id == project_id:
+                if rel_path in p.pinned_files:
+                    p.pinned_files.remove(rel_path)
+                save_all(all_p)
+                return p
+    return None