agent2learn 0.1.2__py3-none-any.whl

agent2learn/audit.py

@@ -0,0 +1,358 @@
+"""Structural coverage audit over what the vault actually holds.
+
+The audit answers one question honestly: *what is missing, and why?*  It never guesses that
+coverage is complete, never treats a title match as proof, and never reports a number it
+cannot substantiate from the manifest and the reconciled content map.
+
+Its most important output is the part users dislike: assignments with no matching course
+content, conversion gaps, integrity gaps, and links that were deliberately not fetched.  A
+report that only counted successes would let a silent ingest failure look like a finished
+archive.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from agent2learn import clock, paths
+from agent2learn import index as course_index
+from agent2learn.vault import Vault
+
+AUDIT_VERSION = 1
+
+_MEDIA_EXTENSIONS = frozenset(
+    {".mp3", ".mp4", ".m4a", ".m4v", ".mov", ".avi", ".wav", ".webm", ".mkv", ".flv"}
+)
+_CITABLE = "markdown_ready"
+_GAP_LABELS: dict[str, str] = {
+    "metadata_only": "known but not fetched",
+    "source_only": "fetched, no markdown twin",
+    "unsupported_format": "no converter for this format",
+    "conversion_gap": "fetched, but conversion produced no markdown twin",
+    "integrity_gap": "on-disk bytes do not match the manifest",
+    "download_gap": "the server did not serve this file; retry the fetch",
+    "external_link": "external link, deliberately not fetched",
+}
+# Tokens that appear in nearly every coursework title and so carry no matching signal.
+# Shared in spirit with ground.py's GENERIC set; kept local because changing one must not
+# silently change the other's scoring.
+_GENERIC = frozenset(
+    {
+        "a", "an", "and", "activity", "assignment", "class", "copy", "for", "home", "in",
+        "lab", "of", "part", "solution", "take", "the", "to", "week",
+    }
+)  # fmt: skip
+
+
+@dataclass(frozen=True)
+class AssignmentMatch:
+    """One assignment and the single best content guess, always labelled as a guess."""
+
+    title: str
+    due_date: str | None
+    best_match: str | None
+    overlap: int
+
+
+@dataclass(frozen=True)
+class CourseAudit:
+    """Everything the report says about one course, computed from local evidence only."""
+
+    course: str
+    code: str
+    name: str
+    topics: int
+    citable: int
+    coverage: dict[str, int] = field(default_factory=dict)
+    links: dict[str, int] = field(default_factory=dict)
+    media: int = 0
+    quizzes: int = 0
+    quizzes_with_due_dates: int = 0
+    assignments: int = 0
+    metadata_gaps: tuple[str, ...] = ()
+    outline_gaps: tuple[tuple[str, str], ...] = ()
+    unmatched_assignments: tuple[AssignmentMatch, ...] = ()
+
+    @property
+    def coverage_percent(self) -> int:
+        """Citable share, floored so a partial archive never rounds up to 100%."""
+        if self.topics == 0:
+            return 0
+        return int(self.citable * 100 // self.topics)
+
+
+def audit_vault(vault: Vault) -> list[CourseAudit]:
+    """Compute a per-course structural audit from the manifest and content maps."""
+    results: list[CourseAudit] = []
+    for map_path in sorted(
+        path for path in paths.walk(vault.root) if path.name == "content_map.json"
+    ):
+        course_dir = map_path.parent.parent
+        rows = course_index.read_content_map(course_dir)["topics"]
+        if not isinstance(rows, list):
+            continue
+        results.append(_audit_course(vault, course_dir, rows))
+    return results
+
+
+def write_audit(vault: Vault, *, timestamp: str | None = None) -> Path:
+    """Write ``.a2l/AUDIT.md`` and return its path."""
+    audits = audit_vault(vault)
+    stamp = timestamp if timestamp is not None else clock.stamp()
+    destination = vault.state() / "AUDIT.md"
+    paths.atomic_write_text(destination, _render(audits, stamp), root=vault.root)
+    return destination
+
+
+def _audit_course(vault: Vault, course_dir: Path, rows: Sequence[object]) -> CourseAudit:
+    coverage: Counter[str] = Counter()
+    links: Counter[str] = Counter()
+    media = 0
+    citable = 0
+    topics = 0
+    titles: list[tuple[str, set[str]]] = []
+
+    for raw in rows:
+        if not isinstance(raw, Mapping):
+            continue
+        topics += 1
+        availability = str(raw.get("availability", "metadata_only"))
+        coverage[availability] += 1
+        if availability == _CITABLE:
+            citable += 1
+        if availability == "external_link":
+            links[_link_kind(raw)] += 1
+        if _is_media(raw):
+            media += 1
+        title = str(raw.get("title") or "")
+        if title:
+            titles.append((title, _terms(title)))
+
+    assignments, assignments_gap = _read_json_list(course_dir / "_meta" / "assignments.json")
+    quizzes, quizzes_gap = _read_json_list(course_dir / "_meta" / "quizzes.json")
+    outline_rows, _ = _read_json_list(course_dir / "_meta" / "outlines.json")
+    outline_gaps = tuple(
+        (str(row.get("source_key") or "unknown"), str(row.get("reason") or "unknown"))
+        for row in outline_rows
+        if row.get("status") == "outline_unavailable"
+    )
+    unmatched = _unmatched_assignments(assignments, titles)
+    metadata_gaps = tuple(gap for gap in (assignments_gap, quizzes_gap) if gap is not None)
+
+    first = next((row for row in rows if isinstance(row, Mapping)), {})
+    return CourseAudit(
+        course=paths.rel_posix(course_dir, vault.root),
+        code=str(first.get("course_code") or course_dir.name),
+        name=str(first.get("course_name") or course_dir.name),
+        topics=topics,
+        citable=citable,
+        coverage=dict(sorted(coverage.items())),
+        links=dict(sorted(links.items())),
+        media=media,
+        quizzes=len(quizzes),
+        quizzes_with_due_dates=sum(1 for row in quizzes if row.get("due_date")),
+        assignments=len(assignments),
+        metadata_gaps=metadata_gaps,
+        outline_gaps=outline_gaps,
+        unmatched_assignments=unmatched,
+    )
+
+
+def _unmatched_assignments(
+    assignments: Sequence[Mapping[str, object]], titles: Sequence[tuple[str, set[str]]]
+) -> tuple[AssignmentMatch, ...]:
+    """Return assignments sharing no distinguishing term with any topic in the course.
+
+    This is deliberately a weak, lexical signal, and it is reported as a prompt to look
+    rather than as a finding.  An assignment with no overlap usually means the brief lives
+    somewhere the API does not expose — a quiz description, an announcement, or a slide.
+    The best-overlapping title is carried along so the student has somewhere to start.
+    """
+    unmatched: list[AssignmentMatch] = []
+    for row in assignments:
+        title = str(row.get("title") or "")
+        wanted = _terms(title)
+        if not wanted:
+            continue
+        # Highest overlap wins; ties break on the title so the report is stable everywhere.
+        ranked = sorted(
+            ((len(wanted & terms), candidate) for candidate, terms in titles),
+            key=lambda pair: (-pair[0], pair[1]),
+        )
+        best_overlap, best_title = ranked[0] if ranked else (0, None)
+        if best_overlap == 0:
+            unmatched.append(
+                AssignmentMatch(
+                    title=title,
+                    due_date=_optional_text(row.get("due_date")),
+                    best_match=best_title,
+                    overlap=0,
+                )
+            )
+    return tuple(sorted(unmatched, key=lambda item: (item.due_date or "", item.title)))
+
+
+def _terms(value: str) -> set[str]:
+    """Tokenise a title into distinguishing terms, dropping generic coursework words."""
+    tokens: set[str] = set()
+    for word in re.findall(r"[a-z0-9]+", value.casefold()):
+        if len(word) > 1 or word.isdigit():
+            tokens.add(word)
+        parts = re.findall(r"[a-z]+|[0-9]+", word)
+        if len(parts) > 1:
+            tokens.update(part for part in parts if len(part) > 1 or part.isdigit())
+    return tokens - _GENERIC
+
+
+def _link_kind(row: Mapping[str, object]) -> str:
+    kind = str(row.get("kind") or "").casefold()
+    if kind in {"lti", "externallink", "link"}:
+        return {"lti": "LTI tool", "externallink": "external link", "link": "external link"}[kind]
+    return kind or "unknown"
+
+
+def _is_media(row: Mapping[str, object]) -> bool:
+    candidate = str(row.get("source_path") or row.get("url_path") or "")
+    return _suffix(candidate) in _MEDIA_EXTENSIONS
+
+
+def _suffix(value: str) -> str:
+    _, _, tail = value.rpartition("/")
+    _, dot, extension = tail.rpartition(".")
+    return f".{extension.casefold()}" if dot else ""
+
+
+def _read_json_list(destination: Path) -> tuple[list[Mapping[str, object]], str | None]:
+    try:
+        with open(os.fspath(paths.long_path(destination)), encoding="utf-8", newline="") as handle:
+            raw = json.load(handle)
+    except FileNotFoundError:
+        return [], None
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return [], f"{destination.name} is unreadable"
+    if not isinstance(raw, list):
+        return [], f"{destination.name} has an invalid root"
+    rows = [row for row in raw if isinstance(row, Mapping)]
+    if len(rows) != len(raw):
+        return rows, f"{destination.name} contains invalid item(s)"
+    return rows, None
+
+
+def _optional_text(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _plural(count: int, singular: str, plural: str | None = None) -> str:
+    return f"{count} {singular}" if count == 1 else f"{count} {plural or singular + 's'}"
+
+
+def _render(audits: Sequence[CourseAudit], stamp: str) -> str:
+    lines = [
+        "# Coverage audit",
+        "",
+        f"Generated {stamp} · audit schema {AUDIT_VERSION}",
+        "",
+        "This report describes only what is in this vault. A gap here means the material was "
+        "not retrievable through the API, not that it does not exist in the course.",
+        "",
+    ]
+
+    if not audits:
+        lines.extend(["No courses have been ingested yet. Run `a2l sync` to begin.", ""])
+        return "\n".join(lines)
+
+    lines.extend(
+        ["## Summary", "", "| Course | Citable | Topics | Coverage |", "| --- | --- | --- | --- |"]
+    )
+    for audit in audits:
+        lines.append(
+            f"| {audit.code} | {audit.citable} | {audit.topics} | {audit.coverage_percent}% |"
+        )
+    lines.append("")
+
+    for audit in audits:
+        lines.extend([f"## {audit.code} — {audit.name}", ""])
+        lines.append(
+            f"{audit.citable} of {audit.topics} topics are citable ({audit.coverage_percent}%)."
+        )
+        lines.append("")
+
+        gaps = [(state, count) for state, count in audit.coverage.items() if state != _CITABLE]
+        if gaps:
+            lines.extend(["### Gaps", "", "| State | Count | Meaning |", "| --- | --- | --- |"])
+            for state, count in gaps:
+                lines.append(f"| `{state}` | {count} | {_GAP_LABELS.get(state, 'unclassified')} |")
+            lines.append("")
+
+        if audit.metadata_gaps:
+            lines.extend(
+                [
+                    "### Metadata gaps",
+                    "",
+                    "The local metadata projection could not be read completely; inventory "
+                    "counts below may be incomplete.",
+                    "",
+                    *[f"- {gap}" for gap in audit.metadata_gaps],
+                    "",
+                ]
+            )
+
+        if audit.outline_gaps:
+            lines.extend(
+                [
+                    "### Outline gaps",
+                    "",
+                    "These outlines could not be rendered from LEARN. They are retried on "
+                    "every sync.",
+                    "",
+                    "| Outline | Reason |",
+                    "| --- | --- |",
+                ]
+            )
+            for source_key, reason in audit.outline_gaps:
+                lines.append(f"| `{source_key}` | {reason} |")
+            lines.append("")
+
+        if audit.links:
+            lines.extend(["### Links not fetched", "", "| Kind | Count |", "| --- | --- |"])
+            for kind, count in audit.links.items():
+                lines.append(f"| {kind} | {count} |")
+            lines.extend(
+                ["", "These are external or licensed targets. Open them in LEARN directly.", ""]
+            )
+
+        counts = [
+            f"- {_plural(audit.assignments, 'assignment')}",
+            f"- {_plural(audit.quizzes, 'quiz', 'quizzes')}"
+            f" ({audit.quizzes_with_due_dates} with due dates)",
+            f"- {_plural(audit.media, 'media file')}",
+        ]
+        lines.extend(["### Inventory", "", *counts, ""])
+
+        if audit.unmatched_assignments:
+            lines.extend(
+                [
+                    "### Assignments with no matching content",
+                    "",
+                    "No topic in this course shares a distinguishing term with these "
+                    "assignments. The brief may have been posted somewhere the API does not "
+                    "expose, such as a quiz description or an announcement.",
+                    "",
+                    "| Assignment | Due |",
+                    "| --- | --- |",
+                ]
+            )
+            for item in audit.unmatched_assignments:
+                lines.append(f"| {item.title} | {item.due_date or '—'} |")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+__all__ = ["AUDIT_VERSION", "AssignmentMatch", "CourseAudit", "audit_vault", "write_audit"]

agent2learn/auth/__init__.py

@@ -0,0 +1,282 @@
+"""Same-device authentication with a CDP path and a universal hidden-TTY fallback."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from urllib.parse import urljoin, urlsplit
+
+import requests
+
+from agent2learn import __version__, config, paths, session
+from agent2learn.errors import AuthenticationError
+from agent2learn.schools import School
+
+from . import paste
+
+_CONNECT_TIMEOUT = 10.0
+_READ_TIMEOUT = 30.0
+
+
+def authenticate(school: School, *, backend: str = "auto") -> session.Session:
+    """Harvest, verify, and persist a minimum same-device LEARN API session.
+
+    ``auto`` deliberately has only one fallback: the tested hidden-TTY paste flow.  It does not
+    opportunistically select another browser automation stack or copy cookies from an everyday
+    browser profile.
+    """
+
+    normalized_backend = backend.casefold()
+    if normalized_backend == "paste":
+        return _authenticate_from_paste(school)
+    if normalized_backend not in {"auto", "cdp"}:
+        raise AuthenticationError(f"unknown authentication backend: {backend}")
+
+    from . import cdp
+
+    try:
+        harvested = cdp.authenticate_browser(school)
+    except AuthenticationError as exc:
+        safe_message = _safe_cdp_error(exc)
+        if normalized_backend == "auto":
+            raise AuthenticationError(f"{safe_message}; fallback: a2l auth --paste") from None
+        raise AuthenticationError(safe_message) from None
+    except (OSError, ValueError) as exc:
+        message = "dedicated browser authentication could not access local state"
+        if normalized_backend == "auto":
+            message += "; fallback: a2l auth --paste"
+        raise AuthenticationError(message) from exc
+
+    stable_id = _verified_id_from_cdp_result(harvested)
+    if stable_id is None:
+        raise AuthenticationError("login could not be verified; try: a2l auth --paste")
+    verified = _with_user_id(harvested, stable_id)
+    _store_verified(verified)
+    return verified
+
+
+def verify(value: session.Session, school: School) -> str | None:
+    """Return the stable D2L identifier after an authenticated, same-origin API check.
+
+    The response is reduced immediately to ``Identifier``.  Display names and the rest of the
+    response never enter the returned value or the persisted ``Session`` projection.
+    """
+
+    if _origin(value.base_url) != _origin(school.base_url):
+        raise AuthenticationError("session and school must use the same HTTPS origin")
+
+    transport = requests.Session()
+    transport.trust_env = False
+    transport.cookies.update(value.requests_cookies())
+    headers = {
+        "User-Agent": f"agent2learn/{__version__} (+https://github.com/ManagementMO/agent2learn)",
+    }
+    if value.xsrf:
+        headers["X-Csrf-Token"] = value.xsrf
+
+    versions_url = urljoin(value.base_url.rstrip("/") + "/", "d2l/api/versions/")
+    try:
+        versions_response = transport.get(
+            versions_url,
+            headers=headers,
+            timeout=(_CONNECT_TIMEOUT, _READ_TIMEOUT),
+            allow_redirects=False,
+        )
+    except requests.RequestException:
+        return None
+    try:
+        if not 200 <= versions_response.status_code < 300:
+            return None
+        if "text/html" in versions_response.headers.get("Content-Type", "").casefold():
+            return None
+        versions = versions_response.json()
+    except (ValueError, requests.RequestException):
+        return None
+    finally:
+        versions_response.close()
+
+    candidates = _lp_versions(versions)
+    for version in candidates:
+        whoami_url = urljoin(
+            value.base_url.rstrip("/") + "/",
+            f"d2l/api/lp/{version}/users/whoami",
+        )
+        try:
+            response = transport.get(
+                whoami_url,
+                headers=headers,
+                timeout=(_CONNECT_TIMEOUT, _READ_TIMEOUT),
+                allow_redirects=False,
+            )
+        except requests.RequestException:
+            continue
+        try:
+            if not 200 <= response.status_code < 300:
+                continue
+            if "text/html" in response.headers.get("Content-Type", "").casefold():
+                continue
+            payload = response.json()
+        except (ValueError, requests.RequestException):
+            continue
+        finally:
+            response.close()
+
+        identifier = _stable_identifier(payload)
+        if identifier is not None:
+            return identifier
+    return None
+
+
+def clear_profile() -> None:
+    """Clear the exported session and remove only the dedicated browser profile after consent."""
+
+    try:
+        session.clear()
+    except OSError as exc:
+        raise AuthenticationError(
+            "saved API session could not be cleared; close it or fix its permissions and retry"
+        ) from exc
+    profile = config.data_dir() / "browser-profile"
+    if paths.is_link(profile):
+        raise AuthenticationError(f"refusing to remove symlinked profile: {profile}")
+    if _profile_is_locked(profile):
+        raise AuthenticationError(
+            f"dedicated browser profile is in use; close it normally before removing: {profile}"
+        )
+    if not paths.long_path(profile).exists():
+        return
+    if not paths.long_path(profile).is_dir():
+        raise AuthenticationError(f"dedicated browser profile is not a directory: {profile}")
+    if not _tty(sys.stdin) or not _tty(sys.stdout):
+        raise AuthenticationError(
+            f"profile removal requires an interactive confirmation for: {profile}"
+        )
+
+    sys.stderr.write(
+        "This removes the dedicated Agent2Learn browser profile and its Waterloo/Duo "
+        "remembered state:\n"
+        f"  {profile}\n"
+        "Type 'yes' to continue: "
+    )
+    sys.stderr.flush()
+    answer = sys.stdin.readline().strip().casefold()
+    sys.stderr.write("\n")
+    if answer != "yes":
+        raise AuthenticationError("profile removal cancelled")
+    try:
+        paths.remove_tree(profile)
+    except OSError as exc:
+        raise AuthenticationError(
+            "dedicated browser profile could not be removed; close it and retry"
+        ) from exc
+
+
+def _authenticate_from_paste(school: School) -> session.Session:
+    blob = paste.read_hidden_multiline()
+    pending = paste.session_from_blob(blob, base_url=school.base_url)
+    stable_id = verify(pending, school)
+    if stable_id is None:
+        raise AuthenticationError("login could not be verified; try: a2l auth --paste")
+    verified = _with_user_id(pending, stable_id)
+    _store_verified(verified)
+    return verified
+
+
+def _store_verified(value: session.Session) -> None:
+    """Translate local session-storage failures into the CLI's stable auth taxonomy."""
+    try:
+        session.store(value)
+    except (OSError, ValueError) as exc:
+        raise AuthenticationError(
+            "verified session could not be saved; check local permissions"
+        ) from exc
+
+
+def _with_user_id(value: session.Session, stable_id: str) -> session.Session:
+    return session.Session(
+        base_url=value.base_url,
+        cookies=value.cookies,
+        xsrf=value.xsrf,
+        harvested_at=value.harvested_at,
+        user_id=stable_id,
+    )
+
+
+def _verified_id_from_cdp_result(value: object) -> str | None:
+    if isinstance(value, session.Session):
+        return value.user_id
+    if isinstance(value, str) and value:
+        return value
+    return None
+
+
+def _safe_cdp_error(exc: AuthenticationError) -> str:
+    """Keep the public auth error generic while retaining a sanitized blocked hostname."""
+
+    prefix = "authentication stopped at undeclared host "
+    raw = str(exc)
+    if raw.startswith(prefix):
+        host = raw[len(prefix) :].split(";", 1)[0].strip()
+        if re.fullmatch(r"[A-Za-z0-9.:-]{1,253}", host):
+            return f"{prefix}{host}"
+    return "dedicated browser authentication failed"
+
+
+def _lp_versions(payload: object) -> tuple[str, ...]:
+    if not isinstance(payload, list):
+        return ()
+    found: list[str] = []
+    for product in payload:
+        if not isinstance(product, dict) or product.get("ProductCode") != "lp":
+            continue
+        versions: list[str] = []
+        latest = product.get("LatestVersion")
+        if isinstance(latest, str):
+            versions.append(latest)
+        supported = product.get("SupportedVersions")
+        if isinstance(supported, list):
+            versions.extend(value for value in supported if isinstance(value, str))
+        for version in versions:
+            if version and version not in found:
+                found.append(version)
+    return tuple(found)
+
+
+def _stable_identifier(payload: object) -> str | None:
+    if not isinstance(payload, dict):
+        return None
+    value = payload.get("Identifier")
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str) and value.strip():
+        return value
+    return None
+
+
+def _origin(value: str) -> tuple[str, str, int]:
+    parsed = urlsplit(value)
+    if parsed.scheme.casefold() != "https" or parsed.hostname is None:
+        raise AuthenticationError("authentication requires an HTTPS school origin")
+    try:
+        port = parsed.port or 443
+    except ValueError as exc:
+        raise AuthenticationError("school origin has an invalid port") from exc
+    return parsed.scheme.casefold(), parsed.hostname.rstrip(".").casefold(), port
+
+
+def _profile_is_locked(profile: Path) -> bool:
+    return any(
+        paths.long_path(profile / marker).exists()
+        for marker in ("SingletonLock", "SingletonSocket", "SingletonCookie")
+    )
+
+
+def _tty(stream: object) -> bool:
+    isatty = getattr(stream, "isatty", None)
+    return bool(callable(isatty) and isatty())
+
+
+__all__ = ["authenticate", "clear_profile", "verify"]