mooring 0.1.0__py3-none-any.whl

mooring/__init__.py

@@ -0,0 +1,3 @@
+"""Mooring: git-free marimo notebook sharing via GitHub."""
+
+__version__ = "0.1.0"

mooring/auth.py

@@ -0,0 +1,197 @@
+"""GitHub OAuth Device Flow and token storage.
+
+Device flow needs only a public client_id (no secret): the app shows a short
+code, the user enters it at https://github.com/login/device, and we poll for
+the resulting token. Tokens are stored in the OS credential store via keyring
+(Windows Credential Manager / macOS Keychain), with a plaintext-file fallback,
+and MOORING_TOKEN overrides everything for CI and tests.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import requests
+
+from mooring import paths
+
+DEVICE_CODE_URL = "https://github.com/login/device/code"
+TOKEN_URL = "https://github.com/login/oauth/access_token"
+SCOPE = "repo"
+KEYRING_SERVICE = "mooring-github"
+KEYRING_USER = "github-token"
+TOKEN_FILE_NAME = "token"
+
+
+class AuthError(Exception):
+    pass
+
+
+@dataclass
+class DeviceCode:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    interval: int
+    expires_in: int
+
+
+@dataclass
+class PollResult:
+    """One poll attempt: exactly one of token/pending is set; pending carries
+    the interval to wait before the next attempt."""
+
+    token: str | None = None
+    interval: int = 5
+
+    @property
+    def pending(self) -> bool:
+        return self.token is None
+
+
+def start_device_flow(client_id: str, session: requests.Session | None = None) -> DeviceCode:
+    http = session or requests
+    resp = http.post(
+        DEVICE_CODE_URL,
+        data={"client_id": client_id, "scope": SCOPE},
+        headers={"Accept": "application/json"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    if "device_code" not in data:
+        raise AuthError(f"GitHub rejected the device-flow request: {data}")
+    return DeviceCode(
+        device_code=data["device_code"],
+        user_code=data["user_code"],
+        verification_uri=data["verification_uri"],
+        interval=int(data.get("interval", 5)),
+        expires_in=int(data.get("expires_in", 900)),
+    )
+
+
+def poll_once(
+    client_id: str,
+    device: DeviceCode,
+    interval: int | None = None,
+    session: requests.Session | None = None,
+) -> PollResult:
+    """Single token-poll attempt. Raises AuthError on terminal failures."""
+    http = session or requests
+    current = interval if interval is not None else device.interval
+    resp = http.post(
+        TOKEN_URL,
+        data={
+            "client_id": client_id,
+            "device_code": device.device_code,
+            "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+        },
+        headers={"Accept": "application/json"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    if "access_token" in data:
+        return PollResult(token=data["access_token"])
+    error = data.get("error", "")
+    if error == "authorization_pending":
+        return PollResult(interval=current)
+    if error == "slow_down":
+        return PollResult(interval=int(data.get("interval", current + 5)))
+    if error == "expired_token":
+        raise AuthError("The login code expired. Start the login again.")
+    if error == "access_denied":
+        raise AuthError("Login was cancelled on github.com.")
+    raise AuthError(f"GitHub login failed: {data.get('error_description', error or data)}")
+
+
+def poll_for_token(
+    client_id: str,
+    device: DeviceCode,
+    session: requests.Session | None = None,
+    sleep=time.sleep,
+    clock=time.monotonic,
+) -> str:
+    """Blocking poll loop used by the CLI; the hub polls via poll_once instead."""
+    deadline = clock() + device.expires_in
+    interval = device.interval
+    while True:
+        if clock() >= deadline:
+            raise AuthError("The login code expired. Start the login again.")
+        result = poll_once(client_id, device, interval=interval, session=session)
+        if result.token:
+            return result.token
+        interval = result.interval
+        sleep(interval)
+
+
+def _token_file() -> "os.PathLike[str]":
+    return paths.user_config_dir() / TOKEN_FILE_NAME
+
+
+def _keyring():
+    try:
+        import keyring
+        import keyring.errors  # noqa: F401
+
+        if keyring.get_keyring() is None:
+            return None
+        return keyring
+    except Exception:  # pragma: no cover - environment-dependent
+        return None
+
+
+def save_token(token: str) -> None:
+    kr = _keyring()
+    if kr is not None:
+        try:
+            kr.set_password(KEYRING_SERVICE, KEYRING_USER, token)
+            return
+        except Exception:  # pragma: no cover - backend-dependent
+            pass
+    path = _token_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(token, "utf-8")
+    try:
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:  # pragma: no cover - chmod is best-effort on Windows
+        pass
+    print(
+        "Warning: no OS credential store available; "
+        f"token saved as plain text at {path}."
+    )
+
+
+def get_token(env: Mapping[str, str] | None = None) -> str | None:
+    env = os.environ if env is None else env
+    if env.get("MOORING_TOKEN"):
+        return env["MOORING_TOKEN"]
+    kr = _keyring()
+    if kr is not None:
+        try:
+            token = kr.get_password(KEYRING_SERVICE, KEYRING_USER)
+            if token:
+                return token
+        except Exception:  # pragma: no cover - backend-dependent
+            pass
+    path = _token_file()
+    if os.path.isfile(path):
+        text = open(path, encoding="utf-8").read().strip()
+        return text or None
+    return None
+
+
+def delete_token() -> None:
+    kr = _keyring()
+    if kr is not None:
+        try:
+            kr.delete_password(KEYRING_SERVICE, KEYRING_USER)
+        except Exception:  # pragma: no cover - includes PasswordDeleteError
+            pass
+    path = _token_file()
+    if os.path.isfile(path):
+        os.remove(path)

mooring/cli.py

@@ -0,0 +1,285 @@
+"""Command-line entry point for mooring."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+from mooring import __version__, config, paths
+
+SELFTEST_PACKAGES = (
+    "marimo",
+    "polars",
+    "altair",
+    "plotly",
+    "openpyxl",
+    "fastexcel",
+    "requests",
+    "keyring",
+    "starlette",
+    "uvicorn",
+    "platformdirs",
+)
+
+
+def _ensure_child_pythonpath() -> None:
+    """Expose bundled packages to child processes (the marimo server and its kernels).
+
+    moonlit activates its extracted site-packages via site.addsitedir(), which
+    subprocesses do not inherit; PYTHONPATH does.
+    """
+    spec = importlib.util.find_spec("marimo")
+    if spec is None or not spec.origin:
+        return
+    site_dir = str(Path(spec.origin).resolve().parents[1])
+    parts = [p for p in os.environ.get("PYTHONPATH", "").split(os.pathsep) if p]
+    if site_dir not in parts:
+        os.environ["PYTHONPATH"] = os.pathsep.join([site_dir, *parts])
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mooring",
+        description="Share marimo notebooks via GitHub without git. "
+        "Run with no arguments to open the browser hub.",
+    )
+    parser.add_argument("--version", action="version", version=f"mooring {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    hub = sub.add_parser("hub", help="open the browser hub (default)")
+    hub.add_argument("--no-browser", action="store_true", help="don't open a browser tab")
+    hub.add_argument("--port", type=int, default=None, help="fixed port for the hub server")
+
+    sub.add_parser("login", help="log in to GitHub via device flow")
+    sub.add_parser("logout", help="forget the stored GitHub token")
+    sub.add_parser("whoami", help="show the logged-in GitHub user")
+    sub.add_parser("status", help="show sync status of workspace files")
+
+    pull = sub.add_parser("pull", help="download changes from the team repo")
+    pull_grp = pull.add_mutually_exclusive_group()
+    pull_grp.add_argument(
+        "--theirs", action="store_true", help="overwrite local edits with remote versions"
+    )
+    pull_grp.add_argument(
+        "--keep-both",
+        action="store_true",
+        help="keep local edits and save remote versions as copies",
+    )
+
+    push = sub.add_parser("push", help="upload local changes to the team repo")
+    push.add_argument("paths", nargs="*", help="specific files to push (default: all changes)")
+    push.add_argument("-m", "--message", default=None, help="commit message")
+
+    open_cmd = sub.add_parser("open", help="open a notebook in the marimo editor")
+    open_cmd.add_argument("path", help="workspace-relative notebook path")
+
+    new = sub.add_parser("new", help="create a new notebook and open it")
+    new.add_argument("name", help="notebook name (e.g. sales-analysis)")
+
+    sub.add_parser("selftest", help="verify the bundled environment")
+    sub.add_parser("version", help="print the version")
+    return parser
+
+
+def _print_paths(cfg: config.Config) -> None:
+    print(f"  config file : {paths.user_config_file()}")
+    print(f"  workspace   : {cfg.workspace()}")
+    print(f"  logs        : {paths.user_log_dir()}")
+
+
+def cmd_selftest(cfg: config.Config) -> int:
+    import importlib.metadata
+
+    print(f"mooring {__version__}  (python {sys.version.split()[0]}, {sys.executable})")
+    failures = []
+    for name in SELFTEST_PACKAGES:
+        try:
+            importlib.import_module(name)
+            version = importlib.metadata.version(name)
+            print(f"  ok  {name} {version}")
+        except Exception as exc:  # noqa: BLE001 - report and continue
+            failures.append(name)
+            print(f"  FAIL {name}: {exc}")
+    _print_paths(cfg)
+    print(f"  PYTHONPATH  : {os.environ.get('PYTHONPATH', '(not set)')}")
+    if cfg.is_configured:
+        print(f"  team repo   : {cfg.repo_slug} (branch {cfg.branch})")
+    else:
+        print("  team repo   : not configured")
+    if failures:
+        print(f"selftest FAILED: {', '.join(failures)}")
+        return 1
+    print("selftest OK")
+    return 0
+
+
+def _require_token() -> str:
+    from mooring import auth
+
+    token = auth.get_token()
+    if not token:
+        sys.exit("Not logged in. Run `mooring login` first.")
+    return token
+
+
+def _client(cfg: config.Config):
+    from mooring.github import GitHubClient
+
+    if not cfg.is_configured:
+        sys.exit(
+            "No team repo configured. Set [github] owner/repo/client_id in "
+            f"{paths.user_config_file()} (or run the hub for guided setup)."
+        )
+    return GitHubClient(_require_token(), cfg.owner, cfg.repo)
+
+
+def cmd_login(cfg: config.Config) -> int:
+    from mooring import auth
+
+    if not cfg.client_id:
+        sys.exit(
+            "No OAuth client_id configured. Set [github] client_id in "
+            f"{paths.user_config_file()}."
+        )
+    device = auth.start_device_flow(cfg.client_id)
+    print(f"Open {device.verification_uri} and enter code: {device.user_code}")
+    print("Waiting for authorization...")
+    token = auth.poll_for_token(cfg.client_id, device)
+    auth.save_token(token)
+    from mooring.github import GitHubClient
+
+    user = GitHubClient(token, cfg.owner, cfg.repo).get_user()
+    print(f"Logged in as {user['login']}.")
+    return 0
+
+
+def cmd_logout() -> int:
+    from mooring import auth
+
+    auth.delete_token()
+    print("Logged out.")
+    return 0
+
+
+def cmd_whoami(cfg: config.Config) -> int:
+    from mooring.github import GitHubClient
+
+    user = GitHubClient(_require_token(), cfg.owner, cfg.repo).get_user()
+    print(user["login"])
+    return 0
+
+
+def cmd_status(cfg: config.Config) -> int:
+    from mooring import sync
+
+    report = sync.status(_client(cfg), cfg)
+    if not report.files:
+        print("Workspace empty and no remote files. Try `mooring new <name>`.")
+        return 0
+    width = max(len(f.path) for f in report.files)
+    for f in report.files:
+        print(f"  {f.path:<{width}}  {f.state.value}")
+    print(report.summary())
+    return 0
+
+
+def cmd_pull(cfg: config.Config, theirs: bool, keep_both: bool) -> int:
+    from mooring import sync
+
+    strategy = (
+        sync.ConflictStrategy.THEIRS
+        if theirs
+        else sync.ConflictStrategy.KEEP_BOTH
+        if keep_both
+        else sync.ConflictStrategy.SKIP
+    )
+    result = sync.pull(_client(cfg), cfg, strategy=strategy)
+    for line in result.lines:
+        print(f"  {line}")
+    print(result.summary())
+    return 0 if not result.skipped_conflicts else 1
+
+
+def cmd_push(cfg: config.Config, only_paths: list[str], message: str | None) -> int:
+    from mooring import sync
+
+    result = sync.push(_client(cfg), cfg, paths=only_paths or None, message=message)
+    for line in result.lines:
+        print(f"  {line}")
+    print(result.summary())
+    return 0 if not result.blocked_conflicts else 1
+
+
+def cmd_open(cfg: config.Config, rel_path: str) -> int:
+    import webbrowser
+
+    from mooring.editor import EditorServer
+
+    workspace = cfg.workspace()
+    target = workspace / rel_path
+    if not target.is_file():
+        sys.exit(f"No such notebook: {target}")
+    server = EditorServer(workspace)
+    server.ensure_started()
+    url = server.url_for(rel_path)
+    print(f"Editor running at {url} (Ctrl+C to stop)")
+    webbrowser.open(url)
+    try:
+        server.wait()
+    except KeyboardInterrupt:
+        server.shutdown()
+    return 0
+
+
+def cmd_new(cfg: config.Config, name: str) -> int:
+    from mooring import notebook_template
+
+    workspace = cfg.workspace()
+    rel_path = notebook_template.create(workspace, name)
+    print(f"Created {rel_path}")
+    return cmd_open(cfg, rel_path)
+
+
+def main(argv: list[str] | None = None) -> int:
+    _ensure_child_pythonpath()
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    command = args.command or "hub"
+    cfg = config.load_config()
+
+    if command == "version":
+        print(f"mooring {__version__}")
+        return 0
+    if command == "selftest":
+        return cmd_selftest(cfg)
+    if command == "hub":
+        from mooring.hub.server import run_hub
+
+        no_browser = getattr(args, "no_browser", False)
+        port = getattr(args, "port", None)
+        return run_hub(cfg, open_browser=not no_browser, port=port)
+    if command == "login":
+        return cmd_login(cfg)
+    if command == "logout":
+        return cmd_logout()
+    if command == "whoami":
+        return cmd_whoami(cfg)
+    if command == "status":
+        return cmd_status(cfg)
+    if command == "pull":
+        return cmd_pull(cfg, args.theirs, args.keep_both)
+    if command == "push":
+        return cmd_push(cfg, args.paths, args.message)
+    if command == "open":
+        return cmd_open(cfg, args.path)
+    if command == "new":
+        return cmd_new(cfg, args.name)
+    parser.error(f"unknown command {command!r}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mooring/config.py

@@ -0,0 +1,72 @@
+"""Layered configuration: packaged defaults <- user config file <- environment."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+from mooring import paths
+
+
+@dataclass(frozen=True)
+class Config:
+    client_id: str = ""
+    owner: str = ""
+    repo: str = ""
+    branch: str = "main"
+    folders: tuple[str, ...] = ("notebooks", "data")
+    warn_file_mb: int = 10
+    max_file_mb: int = 45
+    workspace_path: str = ""
+
+    @property
+    def repo_slug(self) -> str:
+        return f"{self.owner}/{self.repo}"
+
+    @property
+    def is_configured(self) -> bool:
+        return bool(self.client_id and self.owner and self.repo)
+
+    def workspace(self) -> Path:
+        if self.workspace_path:
+            return Path(self.workspace_path).expanduser()
+        return paths.default_workspace(self.repo or "workspace")
+
+
+def _merge(base: dict, override: dict) -> dict:
+    out = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def load_config(
+    user_config_path: Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Config:
+    env = os.environ if env is None else env
+    default_text = resources.files("mooring").joinpath("config_default.toml").read_text("utf-8")
+    data = tomllib.loads(default_text)
+    path = user_config_path if user_config_path is not None else paths.user_config_file()
+    if path.is_file():
+        data = _merge(data, tomllib.loads(path.read_text("utf-8")))
+    gh = data.get("github", {})
+    sync = data.get("sync", {})
+    ws = data.get("workspace", {})
+    return Config(
+        client_id=env.get("MOORING_CLIENT_ID", gh.get("client_id", "")),
+        owner=env.get("MOORING_OWNER", gh.get("owner", "")),
+        repo=env.get("MOORING_REPO", gh.get("repo", "")),
+        branch=env.get("MOORING_BRANCH", gh.get("branch", "main")),
+        folders=tuple(sync.get("folders", ("notebooks", "data"))),
+        warn_file_mb=int(sync.get("warn_file_mb", 10)),
+        max_file_mb=int(sync.get("max_file_mb", 45)),
+        workspace_path=env.get("MOORING_WORKSPACE", ws.get("path", "")),
+    )

mooring/config_default.toml

@@ -0,0 +1,18 @@
+# Default configuration baked into the distributed artifact.
+# An admin edits this file before building, so teammates receive a
+# pre-configured app. Users can override any value in
+# %APPDATA%\mooring\config.toml or via MOORING_* environment variables.
+
+[github]
+client_id = ""   # OAuth app client id (device flow enabled); public, no secret
+owner = ""       # GitHub org or user that owns the shared notebooks repo
+repo = ""        # name of the shared notebooks repo
+branch = "main"
+
+[sync]
+folders = ["notebooks", "data"]
+warn_file_mb = 10
+max_file_mb = 45
+
+[workspace]
+path = ""        # empty = ~/Documents/mooring/<repo>

mooring/editor.py

@@ -0,0 +1,115 @@
+"""Manage the marimo editor as a subprocess.
+
+marimo has no programmatic edit-mode API (only run mode), so we spawn
+`python -m marimo edit <workspace>` as a single directory-mode server and
+open individual notebooks via its `?file=` URL parameter. cli.main() puts the
+bundled site-packages on PYTHONPATH before anything runs, so this subprocess
+— and the kernel processes marimo itself spawns — can import everything even
+when mooring runs from a moonlit-extracted zipapp.
+"""
+
+from __future__ import annotations
+
+import secrets
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+STARTUP_TIMEOUT = 30.0
+
+
+class EditorError(Exception):
+    pass
+
+
+def _free_port() -> int:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+class EditorServer:
+    def __init__(self, workspace: Path) -> None:
+        self.workspace = workspace
+        self.port: int | None = None
+        self.token = secrets.token_urlsafe(16)
+        self._proc: subprocess.Popen | None = None
+
+    @property
+    def running(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    def ensure_started(self) -> None:
+        if self.running:
+            return
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        self.port = _free_port()
+        cmd = [
+            sys.executable,
+            "-m",
+            "marimo",
+            "edit",
+            str(self.workspace),
+            "--headless",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(self.port),
+            "--token-password",
+            self.token,
+            "--skip-update-check",
+        ]
+        self._proc = subprocess.Popen(cmd, cwd=str(self.workspace))
+        self._wait_ready()
+
+    def _wait_ready(self) -> None:
+        deadline = time.monotonic() + STARTUP_TIMEOUT
+        url = f"http://127.0.0.1:{self.port}/"
+        while time.monotonic() < deadline:
+            if self._proc is not None and self._proc.poll() is not None:
+                raise EditorError(
+                    f"marimo exited during startup (code {self._proc.returncode})."
+                )
+            try:
+                urllib.request.urlopen(url, timeout=1)  # noqa: S310 - localhost only
+                return
+            except urllib.error.HTTPError:
+                return  # any HTTP response (401 included) means the server is up
+            except (urllib.error.URLError, OSError, TimeoutError):
+                time.sleep(0.25)
+        raise EditorError("marimo did not become ready in time.")
+
+    def url_for(self, rel_path: str) -> str:
+        if not self.running:
+            raise EditorError("Editor is not running.")
+        query = urllib.parse.urlencode(
+            {"file": rel_path.replace("\\", "/"), "access_token": self.token}
+        )
+        return f"http://127.0.0.1:{self.port}/?{query}"
+
+    def wait(self) -> None:
+        if self._proc is not None:
+            self._proc.wait()
+
+    def shutdown(self) -> None:
+        if not self.running:
+            return
+        proc = self._proc
+        if sys.platform == "win32":
+            # TerminateProcess would orphan marimo's kernel children; kill the tree.
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True,
+                check=False,
+            )
+        else:
+            proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()