moodle-cli 0.1.0__tar.gz

moodle_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Compile package
+        run: uv run python -m compileall moodle_cli
+
+      - name: Smoke test CLI
+        run: uv run moodle --help
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*

moodle_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/moodle-cli/
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import tomllib
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
+          name = project["name"]
+          version = project["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if name != "moodle-cli":
+              raise SystemExit(f"Refusing to publish unexpected package name: {name}")
+          if tag != expected:
+              raise SystemExit(f"Tag {tag} does not match package version {expected}")
+          print(f"Validated release tag {tag} for {name}")
+          PY
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -0,0 +1,59 @@
+name: Publish GitHub Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import tomllib
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
+          name = project["name"]
+          version = project["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if name != "moodle-cli":
+              raise SystemExit(f"Refusing to release unexpected package name: {name}")
+          if tag != expected:
+              raise SystemExit(f"Tag {tag} does not match package version {expected}")
+          print(f"Validated release tag {tag} for {name}")
+          PY
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*.tar.gz
+            dist/*.whl

moodle_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+config.yaml
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

moodle_cli-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

moodle_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Agent Flags
+
+```yaml
+agent_flags:
+  token_economy: prioritize
+  response_style: terse
+  planning_style: minimal
+```
+
+Interpret these as defaults:
+
+- Prefer the shortest sufficient response.
+- Avoid long preambles and repeated summaries.
+- Ask questions only when a wrong assumption is likely to be costly.
+- Make the smallest maintainable change that solves the task.
+
+## Build & Run
+
+```bash
+uv sync                    # install dependencies
+uv run moodle --help       # run CLI
+uv run moodle -v user      # verbose mode (debug logging)
+```
+
+Entry point: `moodle_cli.cli:main` (registered as `moodle` console script in pyproject.toml).
+
+No tests exist yet. No linter/formatter is configured.
+
+## Architecture
+
+Terminal CLI for Moodle LMS that piggybacks on the user's browser session — no API tokens needed.
+
+### API Strategy
+
+Uses Moodle's **internal AJAX endpoint** (`/lib/ajax/service.php`), not the official Web Services token API. This endpoint accepts the `MoodleSession` browser cookie, same as the Moodle web UI. The client first loads an authenticated page to resolve `sesskey`, then tries AJAX APIs and falls back to page scraping when site-specific Moodle restrictions disable some services.
+
+Request format: `POST /lib/ajax/service.php?sesskey={sesskey}&info={function_name}` with JSON body `[{"index": 0, "methodname": "...", "args": {...}}]`. Response: `[{"error": false, "data": ...}]`.
+
+### Data Flow
+
+```
+auth.py (get cookie) → client.py (API calls) → parser.py (JSON→models) → formatter.py/output.py (display)
+         ↑                    ↑
+    env var or            sesskey auto-obtained
+    browser-cookie3       from get_site_info()
+```
+
+- **cli.py**: Click command group. `main()` wraps `cli(standalone_mode=False)` to handle `AuthError`/`MoodleAPIError` cleanly. Client is lazily created via `ctx.obj["get_client"]()` closure — auth only happens when a command actually needs the API.
+- **auth.py**: Priority: `MOODLE_SESSION` env var → browser-cookie3 extraction (Chrome, Firefox, Brave, Edge). Arc browser is not supported by browser-cookie3.
+- **client.py**: `MoodleClient` — holds session cookie, auto-obtains `sesskey`+`userid` on first API call via `_ensure_session()`.
+- **models.py**: Dataclasses (`UserInfo`, `Course`, `Section`, `Activity`) with `to_dict()` for serialization.
+- **parser.py**: Pure functions transforming Moodle JSON dicts → model instances.
+- **formatter.py**: Rich tables (courses) and trees (course sections→activities).
+- **output.py**: `--json`/`--yaml` structured output to stdout.
+- **config.py**: Loads `config.yaml` from CWD or `~/.config/moodle-cli/`. If no `base_url` is configured, it prompts the user, validates the root URL, probes the site, and saves the result. `MOODLE_BASE_URL` env var overrides.
+- **constants.py**: API paths, function names, env var names.
+
+### Adding a New Command
+
+1. Add the Moodle AJAX function name to `constants.py`
+2. Add a method to `MoodleClient` in `client.py` (call `self._ensure_session()` first)
+3. Add model dataclass to `models.py`, parser function to `parser.py`
+4. Add Rich display function to `formatter.py`
+5. Add `@cli.command()` in `cli.py` with `--json`/`--yaml` options
+
+### Adding a New Moodle API Call
+
+All API calls go through `MoodleClient._call(function_name, args)`. It handles the AJAX envelope format and error extraction. Just add a new public method that calls `self._call()` with the right function name.

moodle_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bunizao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moodle_cli-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: moodle-cli
+Version: 0.1.0
+Summary: Terminal-first CLI for Moodle LMS
+Project-URL: Homepage, https://github.com/bunizao/moodle-cli
+Project-URL: Repository, https://github.com/bunizao/moodle-cli
+Project-URL: Issues, https://github.com/bunizao/moodle-cli/issues
+Author: bunizao
+License: MIT License
+        
+        Copyright (c) 2026 bunizao
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: browser-cookie3>=0.19
+Requires-Dist: click>=8.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# moodle-cli
+
+Terminal-first CLI for Moodle LMS that reuses an authenticated browser session.
+
+## Features
+
+- No API token setup required
+- Reads `MoodleSession` from your browser or `MOODLE_SESSION`
+- Works with Moodle AJAX APIs and falls back to authenticated page scraping when needed
+- Terminal output plus `--json` and `--yaml`
+
+## Requirements
+
+- Python 3.10+
+- `uv`
+- An active Moodle browser session, or a `MOODLE_SESSION` environment variable
+
+## Install
+
+```bash
+# Recommended: uv tool
+uv tool install moodle-cli
+
+# Alternative: pipx
+pipx install moodle-cli
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/bunizao/moodle-cli.git
+cd moodle-cli
+uv sync
+```
+
+## Usage
+
+```bash
+moodle --help
+moodle user
+moodle courses
+moodle activities 34637
+moodle update
+```
+
+To upgrade after an update is available:
+
+```bash
+uv tool upgrade moodle-cli
+# or
+pipx upgrade moodle-cli
+```
+
+## Configuration
+
+On first run, if no `base_url` is configured, the CLI will prompt you and write it to `config.yaml` in the project directory or in `~/.config/moodle-cli/`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+Required format:
+
+- Use a full root URL such as `https://school.example.edu`
+- Do not include paths, query strings, or fragments
+- Do not use URLs like `/login/index.php` or `/my/`
+- The CLI validates the URL against Moodle's token endpoint and asks again if it does not look valid
+
+You can also set `MOODLE_BASE_URL` instead of using the interactive prompt.
+You can copy from `config.example.yaml`.
+
+Environment overrides:
+
+- `MOODLE_BASE_URL`
+- `MOODLE_SESSION`
+
+## Development
+
+```bash
+uv run python -m compileall moodle_cli
+uv build
+```

moodle_cli-0.1.0/README.md

@@ -0,0 +1,82 @@
+# moodle-cli
+
+Terminal-first CLI for Moodle LMS that reuses an authenticated browser session.
+
+## Features
+
+- No API token setup required
+- Reads `MoodleSession` from your browser or `MOODLE_SESSION`
+- Works with Moodle AJAX APIs and falls back to authenticated page scraping when needed
+- Terminal output plus `--json` and `--yaml`
+
+## Requirements
+
+- Python 3.10+
+- `uv`
+- An active Moodle browser session, or a `MOODLE_SESSION` environment variable
+
+## Install
+
+```bash
+# Recommended: uv tool
+uv tool install moodle-cli
+
+# Alternative: pipx
+pipx install moodle-cli
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/bunizao/moodle-cli.git
+cd moodle-cli
+uv sync
+```
+
+## Usage
+
+```bash
+moodle --help
+moodle user
+moodle courses
+moodle activities 34637
+moodle update
+```
+
+To upgrade after an update is available:
+
+```bash
+uv tool upgrade moodle-cli
+# or
+pipx upgrade moodle-cli
+```
+
+## Configuration
+
+On first run, if no `base_url` is configured, the CLI will prompt you and write it to `config.yaml` in the project directory or in `~/.config/moodle-cli/`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+Required format:
+
+- Use a full root URL such as `https://school.example.edu`
+- Do not include paths, query strings, or fragments
+- Do not use URLs like `/login/index.php` or `/my/`
+- The CLI validates the URL against Moodle's token endpoint and asks again if it does not look valid
+
+You can also set `MOODLE_BASE_URL` instead of using the interactive prompt.
+You can copy from `config.example.yaml`.
+
+Environment overrides:
+
+- `MOODLE_BASE_URL`
+- `MOODLE_SESSION`
+
+## Development
+
+```bash
+uv run python -m compileall moodle_cli
+uv build
+```

moodle_cli-0.1.0/config.example.yaml

@@ -0,0 +1 @@
+base_url: https://school.example.edu

moodle_cli-0.1.0/moodle_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Terminal-first CLI for Moodle LMS."""
+
+__version__ = "0.1.0"

moodle_cli-0.1.0/moodle_cli/auth.py

@@ -0,0 +1,74 @@
+"""Authentication: extract MoodleSession cookie from env or browser."""
+
+import os
+import logging
+from urllib.parse import urlparse
+
+from moodle_cli.constants import ENV_MOODLE_SESSION
+from moodle_cli.exceptions import AuthError
+
+log = logging.getLogger(__name__)
+
+
+def load_from_env() -> str | None:
+    """Check MOODLE_SESSION environment variable."""
+    value = os.environ.get(ENV_MOODLE_SESSION)
+    if value:
+        log.debug("Using MoodleSession from environment variable")
+    return value
+
+
+def load_from_browser(domain: str) -> str | None:
+    """Extract MoodleSession cookie from browser cookie stores.
+
+    Tries Arc, Chrome, Brave, Edge, Firefox in order.
+    """
+    try:
+        import browser_cookie3  # noqa: F811
+    except ImportError:
+        log.warning("browser-cookie3 not installed; skipping browser cookie extraction")
+        return None
+
+    # browser-cookie3 loaders to try (in priority order)
+    loaders = [
+        ("Chrome", browser_cookie3.chrome),
+        ("Firefox", browser_cookie3.firefox),
+        ("Brave", browser_cookie3.brave),
+        ("Edge", browser_cookie3.edge),
+    ]
+
+    for name, loader in loaders:
+        try:
+            cj = loader(domain_name=domain)
+            for cookie in cj:
+                if cookie.name == "MoodleSession" and domain in (cookie.domain or ""):
+                    log.debug("Found MoodleSession in %s", name)
+                    return cookie.value
+        except Exception as exc:
+            log.debug("Could not read cookies from %s: %s", name, exc)
+
+    return None
+
+
+def get_session(base_url: str) -> str:
+    """Get a valid MoodleSession cookie value.
+
+    Priority: env var → browser cookies.
+    Raises AuthError if no session is found.
+    """
+    # 1. Environment variable
+    session = load_from_env()
+    if session:
+        return session
+
+    # 2. Browser cookies
+    domain = urlparse(base_url).hostname or ""
+    session = load_from_browser(domain)
+    if session:
+        return session
+
+    raise AuthError(
+        "No MoodleSession found. Either:\n"
+        f"  1. Log in to {base_url} in your browser, or\n"
+        f"  2. Set the {ENV_MOODLE_SESSION} environment variable"
+    )