mooring 0.1.0__tar.gz

mooring-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Pythons (3.12 app target, 3.13 for moonlit)
+        run: |
+          uv python install 3.12
+          uv python install 3.13
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build artifacts
+        run: |
+          New-Item -ItemType Directory -Force dist | Out-Null
+          uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring.pyz --python-version 3.12
+          uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring.exe --windows-exe --python-version 3.12
+
+      - name: Smoke test artifact without git on PATH
+        # Strip PATH to the Python directory alone: proves the artifact works
+        # on a machine that has Python but no git or other dev tooling.
+        run: |
+          $py = (uv python find 3.12)
+          $env:PATH = (Split-Path $py)
+          & $py dist/mooring.pyz selftest
+          if ($LASTEXITCODE -ne 0) { exit 1 }
+
+      - name: Upload release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/mooring.pyz
+            dist/mooring.exe
+          generate_release_notes: true

mooring-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.idea

mooring-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: mooring
+Version: 0.1.0
+Summary: Git-free marimo notebook sharing via GitHub
+Requires-Python: <3.13,>=3.12
+Requires-Dist: altair
+Requires-Dist: fastexcel
+Requires-Dist: keyring
+Requires-Dist: marimo>=0.13
+Requires-Dist: openpyxl
+Requires-Dist: platformdirs
+Requires-Dist: plotly
+Requires-Dist: polars
+Requires-Dist: requests
+Requires-Dist: starlette
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+# ⚓ mooring
+
+Git-free [marimo](https://marimo.io) notebook sharing via GitHub.
+
+Mooring is a single-file app (`mooring.pyz` / `mooring.exe`) that lets a team
+of data analysts pull, edit, and push marimo notebooks stored in a shared
+GitHub repo — **without git installed on their machines**. All sync happens
+over the GitHub REST API; the only requirement on an analyst's machine is
+Python 3.12.
+
+Double-clicking the app opens a local browser **hub**: log in to GitHub with
+a one-time device code, see every team notebook with its sync status, pull
+the latest, open notebooks in the bundled marimo editor, and push your
+changes back — one commit per file, with conflicts detected and resolved
+per file (never silently overwritten).
+
+Built with [moonlit](https://github.com/openafterhours/moonlit).
+
+---
+
+## How it works
+
+- **One shared team repo** (e.g. `your-org/notebooks`) holds `notebooks/`
+  and `data/` folders. Everyone pulls from and pushes to it.
+- **No git anywhere.** Pull walks the repo tree via the GitHub Git Data API
+  and downloads only changed blobs; push uses the Contents API with the
+  file's last-known SHA, so GitHub itself rejects writes that would clobber
+  someone else's change.
+- **Three-way change detection.** Mooring computes git blob SHAs locally and
+  keeps a manifest of what was last synced, so it always knows whether a file
+  is modified locally, changed remotely, or conflicted.
+- **Conflicts are explicit.** Pull never overwrites local edits; push blocks
+  conflicted files. The hub offers per-file resolution: *Use remote*,
+  *Keep both*, or *Push as copy* (publishes your version under
+  `name-<your-github-login>.py`).
+- **Frozen package stack.** Notebooks can import anything bundled into the
+  artifact: `polars`, `altair`, `plotly`, `openpyxl`, `fastexcel`,
+  `requests` (plus the standard library). There is no pip at runtime.
+
+## For analysts: install & use
+
+1. Install [Python 3.12](https://www.python.org/downloads/) (tick
+   *"Add python.exe to PATH"*).
+2. Get `mooring.exe` (or `mooring.pyz`) from your admin and put it anywhere,
+   e.g. your Desktop.
+3. Run it (`mooring.exe`, or `python mooring.pyz`). Your browser opens the hub.
+4. Click **Log in with GitHub**, enter the code shown at
+   [github.com/login/device](https://github.com/login/device).
+5. **Pull** to fetch the team's notebooks, **Open** to edit one in marimo,
+   **New notebook** to start fresh, **Push** to share your work.
+
+Notebooks live in `Documents\mooring\<repo>\notebooks\`; data files your
+notebooks read go in `...\<repo>\data\` and sync the same way.
+
+The first launch takes a minute while the app unpacks itself to a local
+cache; later launches are fast.
+
+### CLI (optional)
+
+Everything the hub does is also available from a terminal:
+
+```
+python mooring.pyz login | logout | whoami
+python mooring.pyz status
+python mooring.pyz pull [--theirs | --keep-both]
+python mooring.pyz push [paths...] [-m "message"]
+python mooring.pyz open notebooks/sales.py
+python mooring.pyz new sales-analysis
+python mooring.pyz selftest
+```
+
+## For admins: set up a team
+
+1. **Create the shared repo**, e.g. `your-org/notebooks`, with empty
+   `notebooks/` and `data/` folders. Don't enable git-LFS (the API would
+   deliver pointer files).
+2. **Register a GitHub OAuth app** (Settings → Developer settings → OAuth
+   apps → New). Any homepage/callback URL works; then **enable Device Flow**
+   on the app. Copy the client id — there is no secret to manage.
+   - If the repo lives in an org with third-party-app restrictions, an org
+     owner must approve the OAuth app.
+3. **Bake the config**: edit `src/mooring/config_default.toml` with the
+   client id, owner, repo, and branch.
+4. **Build** (requires [uv](https://docs.astral.sh/uv/)):
+
+   ```
+   uv sync
+   uv run pytest
+   uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring.pyz --python-version 3.12
+   uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring.exe --windows-exe --python-version 3.12
+   ```
+
+   For machines with **no Python at all**, build a folder bundle with
+   embedded CPython instead:
+
+   ```
+   uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring-bundle --bundle-python --python-version 3.12
+   ```
+
+5. **Distribute** the artifact (file share, email, GitHub release — the
+   `.github/workflows/release.yml` workflow builds and attaches artifacts on
+   every `v*` tag).
+
+Users without a baked config get a one-time setup form in the hub instead;
+their values are stored in `%APPDATA%\mooring\config.toml`.
+
+### Changing the bundled notebook packages
+
+Edit `dependencies` in `pyproject.toml`, `uv sync`, rebuild, redistribute.
+Notebooks can only import what's frozen into the artifact.
+
+## Development
+
+```
+uv sync                                  # install everything
+uv run pytest                            # unit tests (no network needed)
+uv run ruff check src tests              # lint
+uv run mooring hub                       # run the hub from source
+uv run python tests/manual_editor_check.py   # editor-subprocess smoke test
+```
+
+Layout: `src/mooring/` — `cli.py` (entry point; also sets PYTHONPATH so the
+marimo subprocess works from inside the packaged artifact), `auth.py` (device
+flow + keyring), `github.py` (REST client), `gitsha.py`/`manifest.py`/`sync.py`
+(the three-way sync engine), `editor.py` (marimo subprocess manager),
+`hub/` (Starlette app + static frontend).
+
+To integration-test sync against a real repo, set `MOORING_TOKEN` (a PAT
+works) plus `MOORING_OWNER`/`MOORING_REPO`/`MOORING_CLIENT_ID` and use the
+CLI against a scratch repository.
+
+## Constraints & notes
+
+- **Python version is pinned.** A `.pyz`/`.exe` built for 3.12 needs the
+  user to have Python 3.12.x; moonlit shows a clear error otherwise. The
+  `--bundle-python` build escapes this entirely.
+- **File sizes**: pushes warn at 10 MB and refuse at 45 MB per file (GitHub
+  Contents API limit). Keep big datasets out of the repo.
+- **Tokens** are stored in the OS credential store (Windows Credential
+  Manager); `repo`-scoped OAuth tokens grant access to all repos the user
+  can reach — use a dedicated machine account org if that's a concern.
+- **Artifact size** is ~110 MB (marimo + polars + plotly + altair). First
+  run extracts to `%LOCALAPPDATA%\moonlit\`; old versions' caches can be
+  deleted freely.

mooring-0.1.0/README.md

@@ -0,0 +1,144 @@
+# ⚓ mooring
+
+Git-free [marimo](https://marimo.io) notebook sharing via GitHub.
+
+Mooring is a single-file app (`mooring.pyz` / `mooring.exe`) that lets a team
+of data analysts pull, edit, and push marimo notebooks stored in a shared
+GitHub repo — **without git installed on their machines**. All sync happens
+over the GitHub REST API; the only requirement on an analyst's machine is
+Python 3.12.
+
+Double-clicking the app opens a local browser **hub**: log in to GitHub with
+a one-time device code, see every team notebook with its sync status, pull
+the latest, open notebooks in the bundled marimo editor, and push your
+changes back — one commit per file, with conflicts detected and resolved
+per file (never silently overwritten).
+
+Built with [moonlit](https://github.com/openafterhours/moonlit).
+
+---
+
+## How it works
+
+- **One shared team repo** (e.g. `your-org/notebooks`) holds `notebooks/`
+  and `data/` folders. Everyone pulls from and pushes to it.
+- **No git anywhere.** Pull walks the repo tree via the GitHub Git Data API
+  and downloads only changed blobs; push uses the Contents API with the
+  file's last-known SHA, so GitHub itself rejects writes that would clobber
+  someone else's change.
+- **Three-way change detection.** Mooring computes git blob SHAs locally and
+  keeps a manifest of what was last synced, so it always knows whether a file
+  is modified locally, changed remotely, or conflicted.
+- **Conflicts are explicit.** Pull never overwrites local edits; push blocks
+  conflicted files. The hub offers per-file resolution: *Use remote*,
+  *Keep both*, or *Push as copy* (publishes your version under
+  `name-<your-github-login>.py`).
+- **Frozen package stack.** Notebooks can import anything bundled into the
+  artifact: `polars`, `altair`, `plotly`, `openpyxl`, `fastexcel`,
+  `requests` (plus the standard library). There is no pip at runtime.
+
+## For analysts: install & use
+
+1. Install [Python 3.12](https://www.python.org/downloads/) (tick
+   *"Add python.exe to PATH"*).
+2. Get `mooring.exe` (or `mooring.pyz`) from your admin and put it anywhere,
+   e.g. your Desktop.
+3. Run it (`mooring.exe`, or `python mooring.pyz`). Your browser opens the hub.
+4. Click **Log in with GitHub**, enter the code shown at
+   [github.com/login/device](https://github.com/login/device).
+5. **Pull** to fetch the team's notebooks, **Open** to edit one in marimo,
+   **New notebook** to start fresh, **Push** to share your work.
+
+Notebooks live in `Documents\mooring\<repo>\notebooks\`; data files your
+notebooks read go in `...\<repo>\data\` and sync the same way.
+
+The first launch takes a minute while the app unpacks itself to a local
+cache; later launches are fast.
+
+### CLI (optional)
+
+Everything the hub does is also available from a terminal:
+
+```
+python mooring.pyz login | logout | whoami
+python mooring.pyz status
+python mooring.pyz pull [--theirs | --keep-both]
+python mooring.pyz push [paths...] [-m "message"]
+python mooring.pyz open notebooks/sales.py
+python mooring.pyz new sales-analysis
+python mooring.pyz selftest
+```
+
+## For admins: set up a team
+
+1. **Create the shared repo**, e.g. `your-org/notebooks`, with empty
+   `notebooks/` and `data/` folders. Don't enable git-LFS (the API would
+   deliver pointer files).
+2. **Register a GitHub OAuth app** (Settings → Developer settings → OAuth
+   apps → New). Any homepage/callback URL works; then **enable Device Flow**
+   on the app. Copy the client id — there is no secret to manage.
+   - If the repo lives in an org with third-party-app restrictions, an org
+     owner must approve the OAuth app.
+3. **Bake the config**: edit `src/mooring/config_default.toml` with the
+   client id, owner, repo, and branch.
+4. **Build** (requires [uv](https://docs.astral.sh/uv/)):
+
+   ```
+   uv sync
+   uv run pytest
+   uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring.pyz --python-version 3.12
+   uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring.exe --windows-exe --python-version 3.12
+   ```
+
+   For machines with **no Python at all**, build a folder bundle with
+   embedded CPython instead:
+
+   ```
+   uvx --python 3.13 moonlit build -e mooring.cli:main -o dist/mooring-bundle --bundle-python --python-version 3.12
+   ```
+
+5. **Distribute** the artifact (file share, email, GitHub release — the
+   `.github/workflows/release.yml` workflow builds and attaches artifacts on
+   every `v*` tag).
+
+Users without a baked config get a one-time setup form in the hub instead;
+their values are stored in `%APPDATA%\mooring\config.toml`.
+
+### Changing the bundled notebook packages
+
+Edit `dependencies` in `pyproject.toml`, `uv sync`, rebuild, redistribute.
+Notebooks can only import what's frozen into the artifact.
+
+## Development
+
+```
+uv sync                                  # install everything
+uv run pytest                            # unit tests (no network needed)
+uv run ruff check src tests              # lint
+uv run mooring hub                       # run the hub from source
+uv run python tests/manual_editor_check.py   # editor-subprocess smoke test
+```
+
+Layout: `src/mooring/` — `cli.py` (entry point; also sets PYTHONPATH so the
+marimo subprocess works from inside the packaged artifact), `auth.py` (device
+flow + keyring), `github.py` (REST client), `gitsha.py`/`manifest.py`/`sync.py`
+(the three-way sync engine), `editor.py` (marimo subprocess manager),
+`hub/` (Starlette app + static frontend).
+
+To integration-test sync against a real repo, set `MOORING_TOKEN` (a PAT
+works) plus `MOORING_OWNER`/`MOORING_REPO`/`MOORING_CLIENT_ID` and use the
+CLI against a scratch repository.
+
+## Constraints & notes
+
+- **Python version is pinned.** A `.pyz`/`.exe` built for 3.12 needs the
+  user to have Python 3.12.x; moonlit shows a clear error otherwise. The
+  `--bundle-python` build escapes this entirely.
+- **File sizes**: pushes warn at 10 MB and refuse at 45 MB per file (GitHub
+  Contents API limit). Keep big datasets out of the repo.
+- **Tokens** are stored in the OS credential store (Windows Credential
+  Manager); `repo`-scoped OAuth tokens grant access to all repos the user
+  can reach — use a dedicated machine account org if that's a concern.
+- **Artifact size** is ~110 MB (marimo + polars + plotly + altair). First
+  run extracts to `%LOCALAPPDATA%\moonlit\`; old versions' caches can be
+  deleted freely.

mooring-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "mooring"
+version = "0.1.0"
+description = "Git-free marimo notebook sharing via GitHub"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "marimo>=0.13",
+    "starlette",
+    "uvicorn",
+    "requests",
+    "keyring",
+    "platformdirs",
+    # notebook stack frozen into the distributed artifact
+    "polars",
+    "altair",
+    "plotly",
+    "openpyxl",
+    "fastexcel",
+]
+
+[project.scripts]
+mooring = "mooring.cli:main"
+
+# moonlit (the .pyz builder) is NOT a dev dependency: it needs Python >=3.13
+# while this project targets the team's 3.12. Invoke it isolated instead:
+#   uvx --python 3.13 moonlit build ...
+[dependency-groups]
+dev = [
+    "pytest",
+    "responses",
+    "ruff",
+    # starlette.testclient backend. starlette now prefers `httpx2` (the
+    # Pydantic-stewarded httpx successor); plain httpx still works behind a
+    # deprecation warning and is kept here as the conservative choice.
+    "httpx",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mooring"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

mooring-0.1.0/src/mooring/__init__.py

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

mooring-0.1.0/src/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)