moodle-cli 0.1.0b0__py3-none-any.whl

moodle_cli/__init__.py

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

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,140 @@
+"""Config loading and first-run base URL setup."""
+
+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
+
+CONFIG_PROMPT = "Enter your Moodle base URL"
+
+
+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 _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 _probe_base_url(base_url: str) -> tuple[bool, str]:
+    """Check whether the configured URL looks reachable and likely Moodle."""
+    try:
+        response = requests.get(f"{base_url}/login/index.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_html = "text/html" in content_type or "<html" in body
+    looks_moodle = "moodle" in body or "log in" in body or "/login/index.php" in body
+
+    if response.status_code >= 400:
+        return False, f"{base_url} returned HTTP {response.status_code}"
+    if not looks_html:
+        return False, f"{base_url} did not return an HTML page"
+    if not looks_moodle:
+        return False, f"{base_url} does not look like a Moodle site"
+
+    return True, ""
+
+
+def _prompt_for_base_url() -> str:
+    click.echo("No Moodle base URL configured.")
+    click.echo("Example: https://school.example.edu")
+
+    while True:
+        value = click.prompt(CONFIG_PROMPT, type=str)
+        try:
+            base_url = _validate_base_url(value)
+        except MoodleCLIError as exc:
+            click.echo(f"Invalid URL: {exc}")
+            continue
+
+        looks_valid, message = _probe_base_url(base_url)
+        if not looks_valid:
+            click.echo(f"Warning: {message}")
+            if not click.confirm("Save this URL anyway?", default=False):
+                continue
+
+        if click.confirm(f"Use {base_url}?", default=True):
+            return base_url
+
+
+def load_config() -> dict:
+    """Load configuration, prompting once for base_url when needed."""
+    config: dict = {}
+    config_file = _find_config_file()
+    if config_file:
+        config = _read_config_file(config_file)
+
+    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 not click.get_text_stream("stdin").isatty():
+        raise MoodleCLIError(
+            "No base_url configured. Set MOODLE_BASE_URL or add base_url to config.yaml before running non-interactively."
+        )
+
+    base_url = _prompt_for_base_url()
+    config["base_url"] = 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

moodle_cli/constants.py

@@ -0,0 +1,19 @@
+"""Default values and API paths."""
+
+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

moodle_cli/formatter.py

@@ -0,0 +1,90 @@
+"""Rich terminal output: tables and trees for Moodle data."""
+
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+from rich.text import Text
+
+from moodle_cli.models import Course, Section, UserInfo
+
+console = Console()
+
+
+def print_user_info(user: UserInfo) -> None:
+    """Display authenticated user info."""
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="bold cyan")
+    table.add_column()
+
+    table.add_row("User", user.fullname)
+    if user.username:
+        table.add_row("Username", user.username)
+    table.add_row("User ID", str(user.userid))
+    table.add_row("Site", user.sitename)
+    table.add_row("URL", user.siteurl)
+    if user.lang:
+        table.add_row("Language", user.lang)
+
+    console.print(table)
+
+
+def print_courses(courses: list[Course]) -> None:
+    """Display enrolled courses as a table."""
+    table = Table(title="Enrolled Courses")
+    table.add_column("ID", style="dim", justify="right")
+    table.add_column("Short Name", style="bold")
+    table.add_column("Full Name")
+    table.add_column("Visible", justify="center")
+
+    for c in courses:
+        visible = "[green]Yes[/]" if c.visible else "[red]No[/]"
+        table.add_row(str(c.id), c.shortname, c.fullname, visible)
+
+    console.print(table)
+
+
+def print_course_contents(sections: list[Section], course_label: str = "Course") -> None:
+    """Display course sections and activities as a tree."""
+    tree = Tree(f"[bold]{course_label}[/bold]")
+
+    for section in sections:
+        label = section.name or f"Section {section.section}"
+        if not section.visible:
+            label += " [dim](hidden)[/dim]"
+        branch = tree.add(f"[bold yellow]{label}[/bold yellow]")
+
+        if not section.activities:
+            branch.add("[dim]No activities[/dim]")
+            continue
+
+        for activity in section.activities:
+            icon = _activity_icon(activity.modname)
+            name = activity.name
+            if not activity.visible:
+                name += " [dim](hidden)[/dim]"
+            branch.add(f"{icon} {name} [dim]({activity.modname})[/dim]")
+
+    console.print(tree)
+
+
+def _activity_icon(modname: str) -> str:
+    """Map Moodle module types to terminal-friendly icons."""
+    icons = {
+        "assign": "[red]A[/]",
+        "quiz": "[magenta]Q[/]",
+        "forum": "[green]F[/]",
+        "resource": "[blue]R[/]",
+        "url": "[cyan]U[/]",
+        "page": "[white]P[/]",
+        "folder": "[yellow]D[/]",
+        "label": "[dim]L[/]",
+        "choice": "[magenta]C[/]",
+        "feedback": "[green]B[/]",
+        "workshop": "[red]W[/]",
+        "glossary": "[cyan]G[/]",
+        "wiki": "[white]K[/]",
+        "book": "[blue]B[/]",
+        "h5pactivity": "[magenta]H[/]",
+        "lti": "[yellow]E[/]",
+    }
+    return icons.get(modname, "[dim]·[/]")

moodle_cli/models.py

@@ -0,0 +1,85 @@
+"""Data models for Moodle entities."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class UserInfo:
+    userid: int
+    username: str
+    fullname: str
+    sitename: str
+    siteurl: str
+    lang: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "userid": self.userid,
+            "username": self.username,
+            "fullname": self.fullname,
+            "sitename": self.sitename,
+            "siteurl": self.siteurl,
+            "lang": self.lang,
+        }
+
+
+@dataclass
+class Course:
+    id: int
+    shortname: str
+    fullname: str
+    category: int = 0
+    visible: bool = True
+    startdate: int = 0
+    enddate: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "shortname": self.shortname,
+            "fullname": self.fullname,
+            "category": self.category,
+            "visible": self.visible,
+            "startdate": self.startdate,
+            "enddate": self.enddate,
+        }
+
+
+@dataclass
+class Activity:
+    id: int
+    name: str
+    modname: str  # e.g. "assign", "forum", "resource", "url"
+    url: str = ""
+    visible: bool = True
+    description: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "modname": self.modname,
+            "url": self.url,
+            "visible": self.visible,
+            "description": self.description,
+        }
+
+
+@dataclass
+class Section:
+    id: int
+    name: str
+    section: int  # position/order number
+    visible: bool = True
+    summary: str = ""
+    activities: list[Activity] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "section": self.section,
+            "visible": self.visible,
+            "summary": self.summary,
+            "activities": [a.to_dict() for a in self.activities],
+        }

moodle_cli/output.py

@@ -0,0 +1,17 @@
+"""Structured output: --json and --yaml support."""
+
+import json
+import sys
+
+import yaml
+
+
+def output_json(data: dict | list) -> None:
+    """Print data as formatted JSON to stdout."""
+    json.dump(data, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def output_yaml(data: dict | list) -> None:
+    """Print data as YAML to stdout."""
+    yaml.dump(data, sys.stdout, default_flow_style=False, allow_unicode=True)

moodle_cli/parser.py

@@ -0,0 +1,57 @@
+"""Parse raw Moodle JSON responses into typed models."""
+
+from moodle_cli.models import Activity, Course, Section, UserInfo
+
+
+def parse_user_info(data: dict) -> UserInfo:
+    return UserInfo(
+        userid=data["userid"],
+        username=data["username"],
+        fullname=data["fullname"],
+        sitename=data["sitename"],
+        siteurl=data["siteurl"],
+        lang=data.get("lang", ""),
+    )
+
+
+def parse_course(data: dict) -> Course:
+    return Course(
+        id=data["id"],
+        shortname=data.get("shortname", ""),
+        fullname=data.get("fullname", ""),
+        category=data.get("category", 0),
+        visible=bool(data.get("visible", True)),
+        startdate=data.get("startdate", 0),
+        enddate=data.get("enddate", 0),
+    )
+
+
+def parse_courses(data: list[dict]) -> list[Course]:
+    return [parse_course(c) for c in data]
+
+
+def parse_activity(data: dict) -> Activity:
+    return Activity(
+        id=data["id"],
+        name=data.get("name", ""),
+        modname=data.get("modname", ""),
+        url=data.get("url", ""),
+        visible=bool(data.get("visible", True)),
+        description=data.get("description", ""),
+    )
+
+
+def parse_section(data: dict) -> Section:
+    modules = data.get("modules", [])
+    return Section(
+        id=data["id"],
+        name=data.get("name", ""),
+        section=data.get("section", 0),
+        visible=bool(data.get("visible", True)),
+        summary=data.get("summary", ""),
+        activities=[parse_activity(m) for m in modules],
+    )
+
+
+def parse_course_contents(data: list[dict]) -> list[Section]:
+    return [parse_section(s) for s in data]

moodle_cli/scraper.py

@@ -0,0 +1,186 @@
+"""HTML scraping helpers for authenticated Moodle pages."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from html import unescape
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from moodle_cli.exceptions import AuthError
+from moodle_cli.models import Activity, Section, UserInfo
+
+
+@dataclass
+class PageContext:
+    """Minimal authenticated context extracted from a Moodle page."""
+
+    sesskey: str
+    user_info: UserInfo
+
+
+def parse_page_context(html: str, base_url: str) -> PageContext:
+    """Extract sesskey and user identity from an authenticated page."""
+    config = _parse_moodle_config(html)
+    soup = BeautifulSoup(html, "html.parser")
+
+    sesskey = str(config.get("sesskey") or "").strip()
+    user_id = int(config.get("userId") or _search_int(html, r'data-user-id="(\d+)"'))
+    fullname = _clean_text_from_node(soup.select_one(".userfullname"))
+    sitename = _extract_sitename(soup)
+    fallback_lang = soup.html.get("lang", "") if soup.html else ""
+    lang = str(config.get("language") or fallback_lang)
+
+    if not sesskey or not user_id or not fullname:
+        raise AuthError("Session appears invalid — could not load authenticated Moodle context")
+
+    return PageContext(
+        sesskey=sesskey,
+        user_info=UserInfo(
+            userid=user_id,
+            username="",
+            fullname=fullname,
+            sitename=sitename,
+            siteurl=base_url,
+            lang=lang,
+        ),
+    )
+
+
+def parse_course_contents_html(html: str, base_url: str) -> list[Section]:
+    """Parse rendered Moodle course HTML into sections and activities."""
+    soup = BeautifulSoup(html, "html.parser")
+    sections: list[Section] = []
+
+    for section_el in soup.select('li[data-for="section"]'):
+        section_id = _safe_int(section_el.get("data-id"))
+        section_num = _safe_int(section_el.get("data-number") or section_el.get("data-sectionnum"))
+        position_name = _clean_text_from_node(section_el.select_one(".course-section-position-name"))
+        main_name = _clean_text_from_node(
+            section_el.select_one("h1.sectionname, h2.sectionname, h3.sectionname")
+            or section_el.select_one('[data-for="section_title"] a')
+            or section_el.select_one('[data-for="section_title"]')
+        )
+        if position_name and main_name and position_name != main_name:
+            section_name = f"{position_name} - {main_name}"
+        else:
+            section_name = main_name or position_name or f"Section {section_num}"
+
+        summary_el = section_el.select_one(".summarytext, [data-for='sectioninfo']")
+        summary = _clean_text_from_node(summary_el)
+        section_visible = "hidden" not in section_el.get("class", [])
+
+        activities: list[Activity] = []
+        seen_activity_ids: set[int] = set()
+        for activity_el in section_el.select('li[data-for="cmitem"]'):
+            activity_id = _safe_int(activity_el.get("data-id"))
+            if activity_id and activity_id in seen_activity_ids:
+                continue
+            if activity_id:
+                seen_activity_ids.add(activity_id)
+
+            classes = activity_el.get("class", [])
+            modname = next((cls[8:] for cls in classes if cls.startswith("modtype_")), "")
+            card = activity_el.select_one('[data-region="activity-card"]') or activity_el.select_one(".activity-item")
+
+            activity_name = _clean_text_from_node(
+                activity_el.select_one(".activityname .instancename")
+                or activity_el.select_one(".activityname")
+                or activity_el.select_one("a.aalink")
+            )
+            if not activity_name and card is not None:
+                activity_name = (card.get("data-activityname") or "").strip()
+            if not activity_name:
+                continue
+
+            link = activity_el.select_one(".activityname a, a.aalink, a[href]")
+            href = link.get("href") if link else ""
+            description = _clean_text_from_node(
+                activity_el.select_one("[data-region='activity-description'], .contentafterlink, .description")
+            )
+            activity_visible = not any(flag in classes for flag in ("hidden", "stealth", "dimmed"))
+
+            activities.append(
+                Activity(
+                    id=activity_id,
+                    name=activity_name,
+                    modname=modname,
+                    url=urljoin(base_url, href) if href else "",
+                    visible=activity_visible,
+                    description=description,
+                )
+            )
+
+        sections.append(
+            Section(
+                id=section_id,
+                name=section_name,
+                section=section_num,
+                visible=section_visible,
+                summary=summary,
+                activities=activities,
+            )
+        )
+
+    return sections
+
+
+def parse_course_section_numbers(html: str, course_id: int) -> list[int]:
+    """Extract the ordered section numbers exposed by the course navigation."""
+    soup = BeautifulSoup(html, "html.parser")
+    section_numbers: list[int] = []
+
+    for link in soup.select(f'a[href*="/course/view.php?id={course_id}&section="]'):
+        href = link.get("href") or ""
+        match = re.search(r"[?&]section=(\d+)", href)
+        if not match:
+            continue
+
+        section_num = int(match.group(1))
+        if section_num not in section_numbers:
+            section_numbers.append(section_num)
+
+    return section_numbers
+
+
+def _parse_moodle_config(html: str) -> dict:
+    match = re.search(r"M\.cfg\s*=\s*({.*?});", html, re.S)
+    if not match:
+        return {}
+
+    try:
+        return json.loads(match.group(1))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _extract_sitename(soup: BeautifulSoup) -> str:
+    title = _clean_text_from_node(soup.title)
+    if "|" in title:
+        return title.rsplit("|", 1)[1].strip()
+    return title
+
+
+def _search_int(html: str, pattern: str) -> int:
+    match = re.search(pattern, html)
+    return int(match.group(1)) if match else 0
+
+
+def _safe_int(value: str | None) -> int:
+    try:
+        return int(value or 0)
+    except ValueError:
+        return 0
+
+
+def _clean_text_from_node(node) -> str:
+    if node is None:
+        return ""
+    return _clean_text(node.get_text(" ", strip=True))
+
+
+def _clean_text(value: str) -> str:
+    return " ".join(unescape(value or "").split())

moodle_cli-0.1.0b0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+moodle_cli/__init__.py,sha256=m04x4InJgeyxvzMnKndLw-ef5zKtcF45SIfjo0eCyAQ,66
+moodle_cli/auth.py,sha256=DBiMu_9niev-AiunRPwn3OJu9Xqg9YJ30VV-VOLyHV4,2184
+moodle_cli/cli.py,sha256=okjfQqox8oSOyrIjNwCORk2V3OMDR-p6HuwBZRaEoDU,4581
+moodle_cli/client.py,sha256=q-gmgoABAw0qvMg3ejnW9l4ZLGG6y5usIB_3AiPwkGM,7457
+moodle_cli/config.py,sha256=dBHhumvsO7XQlFYh5wTtHD9zEOZJ2TA6lnHpP1EkeyA,4649
+moodle_cli/constants.py,sha256=M_Oul6Wg19mbHn2x-RQtHIYMu2mNSdMDK6BoA4oFxdg,638
+moodle_cli/exceptions.py,sha256=n4zyh1T2ET3z8CSYSkbMoP9t4fseRz0cOKW02rXeBuc,441
+moodle_cli/formatter.py,sha256=jLtkCDNE-cq6LseWjwPhM8D2A_vUYs8mKUBhZ15PNUg,2860
+moodle_cli/models.py,sha256=N2ovDmxIBUnOSHLlaYJtpAu6AqohcUR8PVo5rePdwg8,1931
+moodle_cli/output.py,sha256=Eauf9jq6_ibQUr2omqtVpqSnRu77su-GdeL34fz-ahA,438
+moodle_cli/parser.py,sha256=EUcoYhOg03_70uHoX_ZE7QKvSs7eC3rROVvycAbyKMM,1617
+moodle_cli/scraper.py,sha256=LMtis0JBOO6KgYpNW7aqszmKSrX50F91wa0b5Q8YGeQ,6469
+moodle_cli-0.1.0b0.dist-info/METADATA,sha256=Gww1emJzsS9WWWycOzMrGuF8bSa7iU7Ibe-Y-uNxzeE,3331
+moodle_cli-0.1.0b0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+moodle_cli-0.1.0b0.dist-info/entry_points.txt,sha256=fuUGPE0CmD0KfQaGx4pmMnL2I6lTZxrVIb-LebQLNkw,47
+moodle_cli-0.1.0b0.dist-info/licenses/LICENSE,sha256=mNchh_7Qge5KyljHGnGDu3I6eiVijuU22NxtZp5Dgh0,1064
+moodle_cli-0.1.0b0.dist-info/RECORD,,

moodle_cli-0.1.0b0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

moodle_cli-0.1.0b0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+moodle = moodle_cli.cli:main

moodle_cli-0.1.0b0.dist-info/licenses/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.