moodle-cli 0.1.0b0__tar.gz

moodle_cli-0.1.0b0/.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.0b0/.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.0b0/.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.0b0/.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.0b0/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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.0b0/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.0b0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: moodle-cli
+Version: 0.1.0b0
+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: 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.
+
+Repository: <https://github.com/bunizao/moodle-cli>
+
+## 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
+uv sync
+```
+
+## Usage
+
+```bash
+uv run moodle --help
+uv run moodle user
+uv run moodle courses
+uv run moodle activities 34637
+```
+
+## Configuration
+
+On first run, the CLI will ask for your Moodle base URL and save it to `config.yaml`.
+
+Safety checks during setup:
+
+- Requires a full root URL such as `https://school.example.edu`
+- Rejects paths, query strings, and fragments
+- Probes the site before saving
+- Requires explicit confirmation if the target does not look like Moodle
+
+If you prefer to configure it manually, create `config.yaml` in the project directory or in `~/.config/moodle-cli/`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+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
+```
+
+## CI
+
+GitHub Actions runs the following checks on pushes and pull requests:
+
+- Dependency lock sync with `uv`
+- Bytecode compilation
+- CLI smoke check
+- Package build

moodle_cli-0.1.0b0/README.md

@@ -0,0 +1,73 @@
+# moodle-cli
+
+Terminal-first CLI for Moodle LMS that reuses an authenticated browser session.
+
+Repository: <https://github.com/bunizao/moodle-cli>
+
+## 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
+uv sync
+```
+
+## Usage
+
+```bash
+uv run moodle --help
+uv run moodle user
+uv run moodle courses
+uv run moodle activities 34637
+```
+
+## Configuration
+
+On first run, the CLI will ask for your Moodle base URL and save it to `config.yaml`.
+
+Safety checks during setup:
+
+- Requires a full root URL such as `https://school.example.edu`
+- Rejects paths, query strings, and fragments
+- Probes the site before saving
+- Requires explicit confirmation if the target does not look like Moodle
+
+If you prefer to configure it manually, create `config.yaml` in the project directory or in `~/.config/moodle-cli/`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+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
+```
+
+## CI
+
+GitHub Actions runs the following checks on pushes and pull requests:
+
+- Dependency lock sync with `uv`
+- Bytecode compilation
+- CLI smoke check
+- Package build

moodle_cli-0.1.0b0/config.example.yaml

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

moodle_cli-0.1.0b0/moodle_cli/__init__.py

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

moodle_cli-0.1.0b0/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"
+    )

moodle_cli-0.1.0b0/moodle_cli/cli.py

@@ -0,0 +1,142 @@
+"""CLI entry point using Click."""
+
+import logging
+import sys
+
+import click
+from rich.console import Console
+
+from moodle_cli import __version__
+from moodle_cli.auth import get_session
+from moodle_cli.client import MoodleClient
+from moodle_cli.config import load_config
+from moodle_cli.exceptions import AuthError, MoodleAPIError, MoodleCLIError
+from moodle_cli.formatter import print_courses, print_course_contents, print_user_info
+from moodle_cli.output import output_json, output_yaml
+
+console = Console(stderr=True)
+
+
+@click.group()
+@click.option("-v", "--verbose", is_flag=True, help="Enable debug logging.")
+@click.version_option(version=__version__)
+@click.pass_context
+def cli(ctx: click.Context, verbose: bool) -> None:
+    """Terminal-first CLI for Moodle LMS."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        format="%(name)s: %(message)s",
+    )
+
+    config = load_config()
+    ctx.ensure_object(dict)
+    ctx.obj["config"] = config
+
+    # Lazy client creation — only authenticate when a command needs it
+    ctx.obj["_client"] = None
+
+    def get_client() -> MoodleClient:
+        if ctx.obj["_client"] is None:
+            session_cookie = get_session(config["base_url"])
+            ctx.obj["_client"] = MoodleClient(config["base_url"], session_cookie)
+        return ctx.obj["_client"]
+
+    ctx.obj["get_client"] = get_client
+
+
+@cli.command(name="user")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+@click.option("--yaml", "as_yaml", is_flag=True, help="Output as YAML.")
+@click.pass_context
+def user(ctx: click.Context, as_json: bool, as_yaml: bool) -> None:
+    """Show authenticated user info."""
+    client = ctx.obj["get_client"]()
+    info = client.get_site_info()
+
+    if as_json:
+        output_json(info.to_dict())
+    elif as_yaml:
+        output_yaml(info.to_dict())
+    else:
+        print_user_info(info)
+
+
+@cli.command()
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+@click.option("--yaml", "as_yaml", is_flag=True, help="Output as YAML.")
+@click.pass_context
+def courses(ctx: click.Context, as_json: bool, as_yaml: bool) -> None:
+    """List enrolled courses."""
+    client = ctx.obj["get_client"]()
+    course_list = client.get_courses()
+
+    if as_json:
+        output_json([c.to_dict() for c in course_list])
+    elif as_yaml:
+        output_yaml([c.to_dict() for c in course_list])
+    else:
+        print_courses(course_list)
+
+
+@cli.command()
+@click.argument("course_id", type=int)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+@click.option("--yaml", "as_yaml", is_flag=True, help="Output as YAML.")
+@click.pass_context
+def activities(ctx: click.Context, course_id: int, as_json: bool, as_yaml: bool) -> None:
+    """List activities in a course (sections and modules)."""
+    client = ctx.obj["get_client"]()
+    sections = client.get_course_contents(course_id)
+
+    if as_json:
+        output_json([s.to_dict() for s in sections])
+    elif as_yaml:
+        output_yaml([s.to_dict() for s in sections])
+    else:
+        print_course_contents(sections, course_label=f"Course {course_id}")
+
+
+@cli.command()
+@click.argument("course_id", type=int)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+@click.option("--yaml", "as_yaml", is_flag=True, help="Output as YAML.")
+@click.pass_context
+def course(ctx: click.Context, course_id: int, as_json: bool, as_yaml: bool) -> None:
+    """Show course detail with sections."""
+    client = ctx.obj["get_client"]()
+    sections = client.get_course_contents(course_id)
+
+    if as_json:
+        output_json([s.to_dict() for s in sections])
+    elif as_yaml:
+        output_yaml([s.to_dict() for s in sections])
+    else:
+        print_course_contents(sections, course_label=f"Course {course_id}")
+
+
+def main() -> None:
+    """Entry point with error handling."""
+    try:
+        cli(standalone_mode=False)
+    except click.exceptions.Abort:
+        sys.exit(130)
+    except click.exceptions.Exit as e:
+        sys.exit(e.exit_code)
+    except click.ClickException as e:
+        e.show()
+        sys.exit(e.exit_code)
+    except AuthError as e:
+        console.print(f"[bold red]Auth error:[/] {e}")
+        sys.exit(1)
+    except MoodleAPIError as e:
+        console.print(f"[bold red]API error:[/] {e}")
+        if e.error_code:
+            console.print(f"  Error code: {e.error_code}")
+        sys.exit(1)
+    except MoodleCLIError as e:
+        console.print(f"[bold red]Error:[/] {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()