moodle-cli 0.1.0__py3-none-any.whl

moodle_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Terminal-first CLI for Moodle LMS."""
+
+__version__ = "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"
+    )

moodle_cli/cli.py

@@ -0,0 +1,198 @@
+"""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
+from moodle_cli.update_check import check_for_updates
+
+stdout_console = Console()
+stderr_console = Console(stderr=True)
+
+
+def _require_course_id(ctx: click.Context, course_id: int | None) -> int:
+    """Validate a required course ID and show a helpful next step."""
+    if course_id is not None:
+        return course_id
+
+    command_name = ctx.info_name or "course"
+    raise click.UsageError(
+        "Missing argument 'COURSE_ID'. Run 'moodle courses' to list available course IDs, "
+        f"then retry with 'moodle {command_name} COURSE_ID'.",
+        ctx=ctx,
+    )
+
+
+def _print_loading(message: str) -> None:
+    """Print a short loading hint to stderr for slow network calls."""
+    stderr_console.print(f"[dim]{message}[/]")
+
+
+@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",
+    )
+
+    ctx.ensure_object(dict)
+    ctx.obj["_config"] = None
+
+    def get_config() -> dict:
+        if ctx.obj["_config"] is None:
+            ctx.obj["_config"] = load_config()
+        return ctx.obj["_config"]
+
+    ctx.obj["get_config"] = get_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:
+            config = get_config()
+            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."""
+    _print_loading("Loading 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(name="update")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+@click.option("--yaml", "as_yaml", is_flag=True, help="Output as YAML.")
+def update(as_json: bool, as_yaml: bool) -> None:
+    """Check whether a newer moodle-cli version is available."""
+    _print_loading("Checking for updates...")
+    info = check_for_updates()
+
+    if as_json:
+        output_json(info.to_dict())
+    elif as_yaml:
+        output_yaml(info.to_dict())
+    elif info.update_available:
+        stdout_console.print(
+            f"[yellow]Update available:[/] {info.latest_version} "
+            f"(installed: {info.current_version})"
+        )
+        stdout_console.print("Upgrade with:")
+        for command in info.upgrade_commands:
+            stdout_console.print(f"  {command}")
+    else:
+        stdout_console.print(f"[green]{info.package_name} is up to date[/] ({info.current_version})")
+
+
+@cli.command()
+@click.argument("course_id", type=int, required=False)
+@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 | None, as_json: bool, as_yaml: bool) -> None:
+    """List activities in a course (sections and modules)."""
+    course_id = _require_course_id(ctx, course_id)
+    _print_loading(f"Loading activities for course {course_id}...")
+    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, required=False)
+@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 | None, as_json: bool, as_yaml: bool) -> None:
+    """Show course detail with sections."""
+    course_id = _require_course_id(ctx, course_id)
+    _print_loading(f"Loading course {course_id}...")
+    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:
+        stderr_console.print(f"[bold red]Auth error:[/] {e}")
+        sys.exit(1)
+    except MoodleAPIError as e:
+        stderr_console.print(f"[bold red]API error:[/] {e}")
+        if e.error_code:
+            stderr_console.print(f"  Error code: {e.error_code}")
+        sys.exit(1)
+    except MoodleCLIError as e:
+        stderr_console.print(f"[bold red]Error:[/] {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

moodle_cli/client.py

@@ -0,0 +1,206 @@
+"""Moodle client using authenticated page scraping and AJAX fallbacks."""
+
+import logging
+
+import requests
+
+from moodle_cli.constants import (
+    AJAX_SERVICE_PATH,
+    COURSE_PATH,
+    DASHBOARD_PATH,
+    FUNC_GET_COURSES,
+    FUNC_GET_COURSES_BY_TIMELINE,
+    FUNC_GET_COURSE_CONTENTS,
+    FUNC_GET_SITE_INFO,
+)
+from moodle_cli.exceptions import AuthError, MoodleAPIError
+from moodle_cli.models import Course, Section, UserInfo
+from moodle_cli.parser import parse_courses, parse_user_info
+from moodle_cli.scraper import parse_course_contents_html, parse_course_section_numbers, parse_page_context
+
+log = logging.getLogger(__name__)
+
+
+class MoodleClient:
+    """Client for Moodle's authenticated pages and internal AJAX API."""
+
+    def __init__(self, base_url: str, moodle_session: str):
+        self.base_url = base_url
+        self.session = requests.Session()
+        self.session.cookies.set("MoodleSession", moodle_session)
+
+        self._sesskey: str | None = None
+        self._userid: int | None = None
+        self._user_info: UserInfo | None = None
+
+    def _ajax_url(self, function_name: str) -> str:
+        """Build the AJAX service URL."""
+        sesskey = self._sesskey or ""
+        return f"{self.base_url}{AJAX_SERVICE_PATH}?sesskey={sesskey}&info={function_name}"
+
+    def _get(self, path: str, params: dict | None = None) -> requests.Response:
+        """Fetch an authenticated Moodle page."""
+        resp = self.session.get(f"{self.base_url}{path}", params=params)
+        resp.raise_for_status()
+        return resp
+
+    def _call(self, function_name: str, args: dict | None = None) -> dict | list:
+        """Make a single AJAX service call.
+
+        Returns the 'data' field from the first response item.
+        """
+        payload = [
+            {
+                "index": 0,
+                "methodname": function_name,
+                "args": args or {},
+            }
+        ]
+
+        url = self._ajax_url(function_name)
+        log.debug("POST %s", url)
+
+        resp = self.session.post(url, json=payload)
+        resp.raise_for_status()
+
+        result = resp.json()
+
+        # Moodle returns a JSON array
+        if isinstance(result, list) and len(result) > 0:
+            item = result[0]
+            if item.get("error"):
+                exc = item.get("exception", {})
+                raise MoodleAPIError(
+                    exc.get("message", "Unknown API error"),
+                    error_code=exc.get("errorcode"),
+                )
+            return item.get("data", item)
+
+        # Some endpoints return a dict with error info
+        if isinstance(result, dict) and result.get("error"):
+            raise MoodleAPIError(
+                result.get("message", "Unknown error"),
+                error_code=result.get("errorcode"),
+            )
+
+        return result
+
+    def _ensure_session(self) -> None:
+        """Ensure we have an authenticated Moodle context."""
+        if self._sesskey and self._userid:
+            return
+        response = self._get(DASHBOARD_PATH)
+        context = parse_page_context(response.text, self.base_url)
+        self._sesskey = context.sesskey
+        self._userid = context.user_info.userid
+        self._user_info = context.user_info
+
+    def get_site_info(self) -> UserInfo:
+        """Load authenticated user info, falling back to page scraping when needed."""
+        self._ensure_session()
+
+        try:
+            data = self._call(FUNC_GET_SITE_INFO)
+        except MoodleAPIError as exc:
+            if exc.error_code != "servicenotavailable":
+                raise
+            log.debug("Falling back to scraped user info because %s is unavailable", FUNC_GET_SITE_INFO)
+        else:
+            if not isinstance(data, dict) or "userid" not in data:
+                raise AuthError("Session appears invalid — could not retrieve user info")
+
+            self._sesskey = data.get("sesskey") or self._sesskey
+            self._userid = data["userid"]
+            self._user_info = parse_user_info(data)
+
+        if self._user_info is None or self._userid is None:
+            raise AuthError("Session appears invalid — could not retrieve user info")
+
+        log.debug("Authenticated as %s (uid=%d)", self._user_info.fullname, self._userid)
+        return self._user_info
+
+    def get_courses(self) -> list[Course]:
+        """Get all enrolled courses for the authenticated user."""
+        self._ensure_session()
+
+        try:
+            return self._get_courses_timeline()
+        except MoodleAPIError as exc:
+            if exc.error_code != "servicenotavailable":
+                raise
+            log.debug("Falling back to %s because timeline API is unavailable", FUNC_GET_COURSES)
+
+        data = self._call(FUNC_GET_COURSES, {"userid": self._userid})
+        if not isinstance(data, list):
+            return []
+        return parse_courses(data)
+
+    def get_course_contents(self, course_id: int) -> list[Section]:
+        """Get sections and activities for a course."""
+        self._ensure_session()
+
+        try:
+            data = self._call(FUNC_GET_COURSE_CONTENTS, {"courseid": course_id})
+        except MoodleAPIError as exc:
+            if exc.error_code != "servicenotavailable":
+                raise
+            log.debug("Falling back to scraping %s because %s is unavailable", COURSE_PATH, FUNC_GET_COURSE_CONTENTS)
+        else:
+            if isinstance(data, list):
+                from moodle_cli.parser import parse_course_contents
+
+                return parse_course_contents(data)
+            return []
+
+        response = self._get(COURSE_PATH, {"id": course_id})
+        sections = self._scrape_course_contents(course_id, response.text)
+        return sections
+
+    def _get_courses_timeline(self) -> list[Course]:
+        """Get enrolled courses from the dashboard timeline API."""
+        courses: list[dict] = []
+        offset = 0
+
+        while True:
+            data = self._call(
+                FUNC_GET_COURSES_BY_TIMELINE,
+                {"classification": "all", "limit": 100, "offset": offset},
+            )
+            if not isinstance(data, dict):
+                break
+
+            batch = data.get("courses", [])
+            if not isinstance(batch, list) or not batch:
+                break
+
+            courses.extend(batch)
+
+            next_offset = data.get("nextoffset", offset)
+            if not isinstance(next_offset, int) or next_offset <= offset:
+                break
+            offset = next_offset
+
+        return parse_courses(courses)
+
+    def _scrape_course_contents(self, course_id: int, root_html: str) -> list[Section]:
+        """Aggregate sections from section-specific course pages."""
+        section_numbers = parse_course_section_numbers(root_html, course_id)
+        html_pages = [root_html]
+
+        for section_num in section_numbers:
+            if section_num == 0:
+                continue
+            response = self._get(COURSE_PATH, {"id": course_id, "section": section_num})
+            html_pages.append(response.text)
+
+        sections: list[Section] = []
+        seen_sections: set[int] = set()
+        for html in html_pages:
+            for section in parse_course_contents_html(html, self.base_url):
+                section_key = section.section or section.id
+                if section_key in seen_sections:
+                    continue
+                seen_sections.add(section_key)
+                sections.append(section)
+
+        return sections

moodle_cli/config.py

@@ -0,0 +1,161 @@
+"""Config loading and validation."""
+
+from pathlib import Path
+import os
+from urllib.parse import urlparse
+
+import click
+import requests
+import yaml
+
+from moodle_cli.constants import CONFIG_DIR, CONFIG_FILENAME, ENV_MOODLE_BASE_URL
+from moodle_cli.exceptions import MoodleCLIError
+
+
+def _config_candidates() -> list[Path]:
+    return [
+        Path.cwd() / CONFIG_FILENAME,
+        Path(CONFIG_DIR).expanduser() / CONFIG_FILENAME,
+    ]
+
+
+def _find_config_file() -> Path | None:
+    """Search for config.yaml in CWD, then ~/.config/moodle-cli/."""
+    for path in _config_candidates():
+        if path.is_file():
+            return path
+    return None
+
+
+def _default_config_path() -> Path:
+    cwd_config = Path.cwd() / CONFIG_FILENAME
+    if cwd_config.exists():
+        return cwd_config
+    return Path(CONFIG_DIR).expanduser() / CONFIG_FILENAME
+
+
+def _read_config_file(path: Path) -> dict:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def _save_config(path: Path, config: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(config, f, sort_keys=True)
+
+
+def _load_existing_config() -> tuple[dict, Path | None]:
+    config_file = _find_config_file()
+    config = _read_config_file(config_file) if config_file else {}
+    return config, config_file
+
+
+def _validate_base_url(value: str) -> str:
+    raw = value.strip()
+    if not raw:
+        raise MoodleCLIError("Base URL cannot be empty.")
+    if "://" not in raw:
+        raise MoodleCLIError("Base URL must include the scheme, for example https://school.example.edu")
+
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"}:
+        raise MoodleCLIError("Base URL must start with http:// or https://")
+    if not parsed.hostname:
+        raise MoodleCLIError("Base URL must include a hostname")
+    if parsed.query or parsed.fragment:
+        raise MoodleCLIError("Base URL must not include query parameters or fragments")
+    if parsed.path not in {"", "/"}:
+        raise MoodleCLIError("Base URL must be the site root, for example https://school.example.edu")
+
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
+def _missing_base_url_message(config_file: Path | None) -> str:
+    target_path = config_file or _default_config_path()
+    return "\n".join(
+        [
+            "No base_url configured.",
+            f"Add base_url to {target_path} or set MOODLE_BASE_URL.",
+            "Required format:",
+            "  base_url: https://school.example.edu",
+            "Use the site root only. Do not include paths like /login/index.php or /my/.",
+        ]
+    )
+
+
+def _probe_base_url(base_url: str) -> tuple[bool, str]:
+    """Check whether the configured URL exposes a Moodle-specific endpoint."""
+    try:
+        response = requests.get(f"{base_url}/login/token.php", timeout=10, allow_redirects=True)
+    except requests.RequestException as exc:
+        return False, f"Could not reach {base_url}: {exc}"
+
+    content_type = response.headers.get("content-type", "").lower()
+    body = response.text[:5000].lower()
+    looks_json = "application/json" in content_type or body.startswith("{")
+    looks_moodle_token_error = any(
+        marker in body
+        for marker in [
+            '"errorcode":"missingparam"',
+            '"errorcode":"invalidparameter"',
+            '"errorcode":"invalidlogin"',
+            "a required parameter (username) was missing",
+        ]
+    )
+
+    if response.status_code >= 400:
+        return False, f"{base_url} returned HTTP {response.status_code}"
+    if looks_json and looks_moodle_token_error:
+        return True, ""
+
+    return False, f"{base_url} does not expose the expected Moodle token endpoint"
+
+
+def _prompt_for_base_url() -> str:
+    click.secho("\nConfiguration required", fg="yellow", bold=True)
+    click.secho("Moodle base URL is not configured yet.", fg="yellow")
+    click.secho("Required format: https://school.example.edu", fg="cyan", bold=True)
+    click.echo("Use the site root only. Do not include paths like /login/index.php or /my/.")
+    click.echo()
+
+    while True:
+        try:
+            base_url = _validate_base_url(
+                click.prompt(
+                    click.style("Moodle base URL", fg="green", bold=True),
+                    prompt_suffix=click.style(" > ", fg="green", bold=True),
+                    type=str,
+                )
+            )
+        except MoodleCLIError as exc:
+            click.secho(f"Invalid URL: {exc}", fg="red")
+            continue
+
+        looks_valid, message = _probe_base_url(base_url)
+        if looks_valid:
+            return base_url
+
+        click.secho(f"Validation failed: {message}", fg="red")
+
+
+def load_config() -> dict:
+    """Load configuration and require an explicit base_url."""
+    config, config_file = _load_existing_config()
+
+    if env_url := os.environ.get(ENV_MOODLE_BASE_URL):
+        config["base_url"] = _validate_base_url(env_url)
+        return config
+
+    if base_url := config.get("base_url"):
+        config["base_url"] = _validate_base_url(str(base_url))
+        return config
+
+    if click.get_text_stream("stdin").isatty():
+        config["base_url"] = _prompt_for_base_url()
+        target_path = config_file or _default_config_path()
+        _save_config(target_path, config)
+        click.echo(f"Saved base_url to {target_path}")
+        return config
+
+    raise MoodleCLIError(_missing_base_url_message(config_file))

moodle_cli/constants.py

@@ -0,0 +1,22 @@
+"""Default values and API paths."""
+
+PACKAGE_NAME = "moodle-cli"
+PYPI_JSON_URL = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
+
+AJAX_SERVICE_PATH = "/lib/ajax/service.php"
+DASHBOARD_PATH = "/my/"
+COURSE_PATH = "/course/view.php"
+
+# Moodle AJAX function names
+FUNC_GET_SITE_INFO = "core_webservice_get_site_info"
+FUNC_GET_COURSES = "core_enrol_get_users_courses"
+FUNC_GET_COURSES_BY_TIMELINE = "core_course_get_enrolled_courses_by_timeline_classification"
+FUNC_GET_COURSE_CONTENTS = "core_course_get_contents"
+
+# Config file locations (checked in order)
+CONFIG_FILENAME = "config.yaml"
+CONFIG_DIR = "~/.config/moodle-cli"
+
+# Environment variable names
+ENV_MOODLE_SESSION = "MOODLE_SESSION"
+ENV_MOODLE_BASE_URL = "MOODLE_BASE_URL"

moodle_cli/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exceptions for moodle-cli."""
+
+
+class MoodleCLIError(Exception):
+    """Base exception for moodle-cli."""
+
+
+class AuthError(MoodleCLIError):
+    """Authentication failed — no valid session found."""
+
+
+class MoodleAPIError(MoodleCLIError):
+    """Moodle API returned an error response."""
+
+    def __init__(self, message: str, error_code: str | None = None):
+        super().__init__(message)
+        self.error_code = error_code