agent2learn 0.1.2__py3-none-any.whl

agent2learn/clock.py

@@ -0,0 +1,39 @@
+"""The single wall-clock seam for everything that reaches the vault.
+
+Vault bytes must be reproducible: the golden-vault test hashes every generated file and
+compares the map across Windows, macOS, and Linux.  A module that reads the clock directly
+is therefore untestable for byte parity, because two runs can never agree.  Every writer
+that stamps a timestamp into a manifest, twin, index, snapshot, or audit calls through here
+so a test can freeze time in exactly one place.
+
+``tests/test_no_forbidden_calls.py`` enforces this: ``datetime.now`` may only appear in this
+module and in the authentication and transport paths, which never write vault content.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+def now() -> datetime:
+    """Return the current instant as an aware UTC ``datetime``."""
+    return datetime.now(UTC)
+
+
+def stamp() -> str:
+    """Return the current instant as the vault's canonical ``Z``-suffixed ISO-8601 string.
+
+    The vault stores ``2026-08-25T12:00:00Z`` rather than ``+00:00`` so timestamps compare
+    as plain strings and sort lexicographically in the same order as chronologically.
+    """
+    return to_stamp(now())
+
+
+def to_stamp(value: datetime) -> str:
+    """Render an aware UTC ``datetime`` in the vault's canonical timestamp form."""
+    if value.tzinfo is None:
+        raise ValueError("timestamp must be timezone-aware")
+    return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+__all__ = ["now", "stamp", "to_stamp"]

agent2learn/config.py

@@ -0,0 +1,205 @@
+"""Platform-correct machine configuration and state locations.
+
+The config file is intentionally small and local. Known fields are validated strictly, while
+unknown top-level JSON fields are retained as opaque future-version data and never interpreted by
+this version. This permits a downgrade without silently deleting newer settings.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TypeAlias, cast
+
+from platformdirs import PlatformDirs
+
+from agent2learn import paths
+
+JSONValue: TypeAlias = None | bool | int | float | str | list["JSONValue"] | dict[str, "JSONValue"]
+
+DIRS = PlatformDirs("agent2learn", appauthor=False, ensure_exists=True)
+DEFAULT_VAULT = Path.home() / "agent2learn"
+_KNOWN_KEYS = frozenset(
+    {
+        "vault",
+        "school",
+        "submit_enabled",
+        "include_discussions",
+        "include_grades",
+        "ocr_words_per_page",
+    }
+)
+
+
+@dataclass(frozen=True)
+class Config:
+    """The user-controlled Agent2Learn configuration.
+
+    ``submit_enabled`` is only the first acknowledgement gate; it is never sufficient to perform
+    a submission. A fresh interactive confirmation remains mandatory for every file.
+    """
+
+    vault: Path = field(default_factory=lambda: DEFAULT_VAULT)
+    school: str = "uwaterloo"
+    submit_enabled: bool = False
+    include_discussions: bool = False
+    include_grades: bool = False
+    ocr_words_per_page: int = 80
+    extras: dict[str, JSONValue] = field(default_factory=dict)
+
+
+def config_path() -> Path:
+    """Return the per-user JSON config path and ensure its directory exists."""
+
+    return _directory(DIRS.user_config_path) / "config.json"
+
+
+def state_dir() -> Path:
+    """Return the machine-state directory for sessions and calibration."""
+
+    return _directory(DIRS.user_state_path)
+
+
+def data_dir() -> Path:
+    """Return the per-user data directory used for the dedicated browser profile."""
+
+    return _directory(DIRS.user_data_path)
+
+
+def log_path() -> Path:
+    """Return the primary bounded local log path."""
+
+    return _directory(DIRS.user_log_path) / "a2l.log"
+
+
+def load() -> Config:
+    """Load and validate config, returning privacy-safe defaults when it is absent."""
+
+    destination = config_path()
+    try:
+        linked = paths.is_link(destination)
+        present = paths.long_path(destination).is_file()
+    except OSError as exc:
+        raise ValueError("config file is unreadable") from exc
+    if linked:
+        raise ValueError("config file must not be a symlink")
+    if not present:
+        return Config()
+
+    try:
+        with open(
+            os.fspath(paths.long_path(destination)),
+            encoding="utf-8",
+            newline="",
+        ) as handle:
+            raw: Any = json.load(handle)
+    except FileNotFoundError:
+        # The file can disappear between is_file() and open(); absence is still the default case.
+        return Config()
+    except (UnicodeError, json.JSONDecodeError) as exc:
+        raise ValueError("config file is not valid JSON") from exc
+    except OSError as exc:
+        raise ValueError("config file is unreadable") from exc
+
+    if not isinstance(raw, dict):
+        raise ValueError("config root must be a JSON object")
+
+    data: dict[str, JSONValue] = {
+        cast(str, key): cast(JSONValue, value) for key, value in raw.items()
+    }
+    vault = _read_vault(data)
+    school = _read_string(data, "school", "uwaterloo")
+    submit_enabled = _read_bool(data, "submit_enabled", False)
+    include_discussions = _read_bool(data, "include_discussions", False)
+    include_grades = _read_bool(data, "include_grades", False)
+    ocr_words_per_page = _read_positive_int(data, "ocr_words_per_page", 80)
+    extras = {key: value for key, value in data.items() if key not in _KNOWN_KEYS}
+    return Config(
+        vault=vault,
+        school=school,
+        submit_enabled=submit_enabled,
+        include_discussions=include_discussions,
+        include_grades=include_grades,
+        ocr_words_per_page=ocr_words_per_page,
+        extras=extras,
+    )
+
+
+def save(cfg: Config) -> None:
+    """Canonicalize and atomically save ``cfg`` through the shared path primitive."""
+
+    if cfg.extras.keys() & _KNOWN_KEYS:
+        raise ValueError("extras cannot replace a known config key")
+    if not cfg.school:
+        raise ValueError("school must not be empty")
+
+    payload: dict[str, JSONValue] = {
+        "include_discussions": cfg.include_discussions,
+        "include_grades": cfg.include_grades,
+        "ocr_words_per_page": cfg.ocr_words_per_page,
+        "school": cfg.school,
+        "submit_enabled": cfg.submit_enabled,
+        "vault": os.fspath(cfg.vault),
+        **cfg.extras,
+    }
+    text = (
+        json.dumps(
+            payload,
+            ensure_ascii=False,
+            sort_keys=True,
+            indent=2,
+            separators=(",", ": "),
+        )
+        + "\n"
+    )
+    destination = config_path()
+    paths.atomic_write_text(destination, text)
+
+
+def _directory(value: str | os.PathLike[str]) -> Path:
+    directory = Path(value)
+    paths.long_path(directory).mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def _read_vault(data: dict[str, JSONValue]) -> Path:
+    value = data.get("vault", os.fspath(DEFAULT_VAULT))
+    if not isinstance(value, str) or not value:
+        raise ValueError("vault must be a non-empty string")
+    return Path(value).expanduser()
+
+
+def _read_string(data: dict[str, JSONValue], key: str, default: str) -> str:
+    value = data.get(key, default)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{key} must be a non-empty string")
+    return value
+
+
+def _read_bool(data: dict[str, JSONValue], key: str, default: bool) -> bool:
+    value = data.get(key, default)
+    if not isinstance(value, bool):
+        raise ValueError(f"{key} must be a boolean")
+    return value
+
+
+def _read_positive_int(data: dict[str, JSONValue], key: str, default: int) -> int:
+    value = data.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError(f"{key} must be a positive integer")
+    return value
+
+
+__all__ = [
+    "DIRS",
+    "DEFAULT_VAULT",
+    "Config",
+    "config_path",
+    "data_dir",
+    "load",
+    "log_path",
+    "save",
+    "state_dir",
+]

agent2learn/console.py

@@ -0,0 +1,229 @@
+"""Terminal presentation and privacy-preserving local diagnostics."""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import os
+import sys
+from logging.handlers import RotatingFileHandler
+from typing import Any, TextIO
+
+from rich.console import Console
+
+from agent2learn import __version__, config, paths
+
+_UNICODE_GLYPH = {"ok": "✓", "warn": "⚠", "fail": "✗", "info": "ℹ"}
+_ASCII_GLYPH = {"ok": "[ok]", "warn": "[!]", "fail": "[x]", "info": "[-]"}
+_ALLOWED_EVENTS = frozenset(
+    {
+        "auth",
+        "auth_checked",
+        "audit",
+        "calendar",
+        "convert",
+        "courses",
+        "diff",
+        "doctor",
+        "fetch",
+        "submit",
+        "sync",
+        "sync_completed",
+        "upgrade",
+    }
+)
+_ALLOWED_DIAGNOSTIC_CODES = frozenset(
+    {
+        "API_UNAVAILABLE",
+        "AUTH_EXPIRED",
+        "CONFIG_INVALID",
+        "CONVERSION_GAP",
+        "DOCTOR_REPORT",
+        "INTEGRITY_GAP",
+        "SUBMISSION_BLOCKED",
+        "SYNC_OK",
+    }
+)
+_ALLOWED_STATUSES = frozenset({"completed", "failure", "skipped", "started", "success", "warning"})
+_SAFE_EXCEPTION_CLASSES = frozenset(
+    {
+        "A2LError",
+        "AuthenticationError",
+        "ConversionError",
+        "DownloadError",
+        "FileNotFoundError",
+        "NotConfigured",
+        "OSError",
+        "PermissionError",
+        "RuntimeError",
+        "SessionExpired",
+        "TimeoutError",
+        "ValueError",
+    }
+)
+_LOGGER_NAME = "agent2learn"
+_HANDLER_MARKER = "_agent2learn_allowlisted_handler"
+_MAX_BYTES = 1_048_576
+_BACKUP_COUNT = 4
+
+
+def _glyphs_for(stream: TextIO) -> dict[str, str]:
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        return dict(_ASCII_GLYPH)
+    try:
+        "✓".encode(encoding)
+    except (LookupError, UnicodeEncodeError):
+        return dict(_ASCII_GLYPH)
+    return dict(_UNICODE_GLYPH)
+
+
+GLYPH = _glyphs_for(sys.stdout)
+
+
+def out() -> Console:
+    """Return a Rich console with color disabled for non-TTY and ``NO_COLOR`` output."""
+
+    stream = sys.stdout
+    terminal = _is_tty(stream)
+    no_color = "NO_COLOR" in os.environ or not terminal
+    supports_unicode = _glyphs_for(stream) == _UNICODE_GLYPH
+    return Console(
+        file=stream,
+        force_terminal=terminal,
+        no_color=no_color,
+        emoji=supports_unicode,
+    )
+
+
+def get_logger() -> logging.Logger:
+    """Return the package logger; handlers are installed by ``configure_logging``."""
+
+    return logging.getLogger(_LOGGER_NAME)
+
+
+def configure_logging(*, verbose: bool = False) -> logging.Logger:
+    """Install a bounded handler that writes only structured allowlisted events.
+
+    ``verbose`` changes diagnostic level, never the data schema. Ordinary logger calls without
+    the private structured payload are rejected by the handler filter, so a future traceback or
+    request debug string cannot accidentally become a local log record.
+    """
+
+    logger = get_logger()
+    logger.setLevel(logging.DEBUG if verbose else logging.INFO)
+    logger.propagate = False
+    for handler in list(logger.handlers):
+        if getattr(handler, _HANDLER_MARKER, False):
+            logger.removeHandler(handler)
+            handler.close()
+
+    handler = RotatingFileHandler(
+        os.fspath(paths.long_path(config.log_path())),
+        maxBytes=_MAX_BYTES,
+        backupCount=_BACKUP_COUNT,
+        encoding="utf-8",
+        delay=True,
+    )
+    setattr(handler, _HANDLER_MARKER, True)
+    handler.setLevel(logging.DEBUG if verbose else logging.INFO)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    handler.addFilter(_AllowlistedFilter())
+    logger.addHandler(handler)
+    return logger
+
+
+def close_owned_handlers() -> None:
+    """Close only Agent2Learn's allowlisted handlers without creating a replacement.
+
+    Privacy log purge calls this before unlinking the five known rotating files.  Keeping the
+    helper here means the privacy layer does not need to depend on the logger's private marker or
+    accidentally close handlers belonging to an embedding application.
+    """
+
+    logger = get_logger()
+    for handler in list(logger.handlers):
+        if getattr(handler, _HANDLER_MARKER, False):
+            logger.removeHandler(handler)
+            handler.close()
+
+
+def log_event(
+    event: str,
+    *,
+    diagnostic_code: str | None = None,
+    stage_ms: int | float | None = None,
+    status: str | None = None,
+    exception: BaseException | type[BaseException] | None = None,
+    **context: object,
+) -> None:
+    """Write a safe event and deliberately discard all arbitrary context.
+
+    ``context`` exists so callers can pass rich operation context without making it part of the
+    persistence contract. URLs, headers, bodies, cookies, identities, course data, filenames,
+    grades, discussions, drafts, and confirmation phrases are never serialized.
+    """
+
+    del context
+    if event not in _ALLOWED_EVENTS:
+        raise ValueError("event is not an allowlisted diagnostic event")
+    payload: dict[str, object] = {"event": event, "package_version": __version__}
+    if diagnostic_code is not None:
+        if diagnostic_code not in _ALLOWED_DIAGNOSTIC_CODES:
+            raise ValueError("diagnostic_code is not an allowlisted diagnostic code")
+        payload["diagnostic_code"] = diagnostic_code
+    if stage_ms is not None:
+        if isinstance(stage_ms, bool) or not isinstance(stage_ms, (int, float)):
+            raise ValueError("stage_ms must be a finite non-negative number")
+        if not math.isfinite(stage_ms) or stage_ms < 0:
+            raise ValueError("stage_ms must be a finite non-negative number")
+        payload["stage_ms"] = stage_ms
+    if status is not None:
+        if status not in _ALLOWED_STATUSES:
+            raise ValueError("status is not an allowlisted diagnostic status")
+        payload["status"] = status
+    if exception is not None:
+        exception_name = (
+            exception.__name__ if isinstance(exception, type) else type(exception).__name__
+        )
+        payload["exception_class"] = (
+            exception_name if exception_name in _SAFE_EXCEPTION_CLASSES else "Exception"
+        )
+
+    logger = get_logger()
+    if not any(getattr(handler, _HANDLER_MARKER, False) for handler in logger.handlers):
+        logger = configure_logging()
+    logger.info("structured event", extra={"_a2l_payload": payload})
+
+
+class _AllowlistedFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        payload: Any = getattr(record, "_a2l_payload", None)
+        if not isinstance(payload, dict):
+            return False
+        record.msg = json.dumps(
+            payload,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+        record.args = ()
+        return True
+
+
+def _is_tty(stream: TextIO) -> bool:
+    try:
+        return bool(stream.isatty())
+    except (AttributeError, OSError):
+        return False
+
+
+__all__ = [
+    "GLYPH",
+    "close_owned_handlers",
+    "configure_logging",
+    "get_logger",
+    "log_event",
+    "out",
+]