studyctl 2.0.0__py3-none-any.whl

studyctl/scheduler.py

@@ -0,0 +1,242 @@
+"""Cross-platform scheduled job management (macOS launchd + Linux systemd/cron)."""
+
+from __future__ import annotations
+
+import platform
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from textwrap import dedent
+
+JOBS_DIR = Path.home() / ".config" / "studyctl" / "jobs"
+
+
+@dataclass
+class Job:
+    name: str
+    command: str  # Uses ~ for portability
+    schedule: str  # Human-readable: "every 2h", "daily 7am"
+    description: str = ""
+
+
+DEFAULT_JOBS = [
+    Job(
+        "session-export", "~/.local/bin/session-export", "every 2h", "Extract agent sessions to DB"
+    ),
+    Job(
+        "studyctl-sync", "~/.local/bin/studyctl sync --all", "daily 7am", "Sync notes to NotebookLM"
+    ),
+    Job("studyctl-push", "~/.local/bin/studyctl state push", "every 4h", "Push state to hub"),
+]
+
+
+def _is_macos() -> bool:
+    return platform.system() == "Darwin"
+
+
+# ── macOS launchd ──────────────────────────────────────────────────────────
+
+
+def _launchd_plist(job: Job, username: str) -> str:
+    home = f"/Users/{username}" if _is_macos() else f"/home/{username}"
+    cmd_parts = job.command.replace("~", home).split()
+    args_xml = "\n        ".join(f"<string>{a}</string>" for a in cmd_parts)
+
+    hour_tpl = "<key>Hour</key><integer>{h}</integer>"
+    min_tpl = "<key>Minute</key><integer>{m}</integer>"
+
+    def _cal_dict(h: int, m: int = 0) -> str:
+        return f"        <dict>{hour_tpl.format(h=h)}{min_tpl.format(m=m)}</dict>"
+
+    cal_key = "    <key>StartCalendarInterval</key>\n"
+    if "every 2h" in job.schedule:
+        entries = "\n".join(_cal_dict(h) for h in range(8, 23, 2))
+        schedule = f"{cal_key}    <array>\n{entries}\n    </array>"
+    elif "every 4h" in job.schedule:
+        entries = "\n".join(_cal_dict(h, 30) for h in range(8, 23, 4))
+        schedule = f"{cal_key}    <array>\n{entries}\n    </array>"
+    elif "daily" in job.schedule:
+        hour = 7
+        if "am" in job.schedule:
+            hour = int(job.schedule.split("daily")[1].strip().replace("am", "").strip())
+        schedule = (
+            f"{cal_key}"
+            "    <dict>\n"
+            f"        {hour_tpl.format(h=hour)}\n"
+            f"        {min_tpl.format(m=0)}\n"
+            "    </dict>"
+        )
+    else:
+        schedule = "    <key>StartInterval</key>\n    <integer>3600</integer>"
+
+    return dedent(f"""\
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+    <plist version="1.0">
+    <dict>
+        <key>Label</key>
+        <string>com.studyctl.{job.name}</string>
+        <key>ProgramArguments</key>
+        <array>
+            {args_xml}
+        </array>
+    {schedule}
+        <key>StandardOutPath</key>
+        <string>{home}/.local/share/studyctl/logs/{job.name}.log</string>
+        <key>StandardErrorPath</key>
+        <string>{home}/.local/share/studyctl/logs/{job.name}.err</string>
+        <key>EnvironmentVariables</key>
+        <dict>
+            <key>PATH</key>
+            <string>{home}/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+        </dict>
+    </dict>
+    </plist>""")
+
+
+def _launchd_install(job: Job, username: str) -> bool:
+    label = f"com.studyctl.{job.name}"
+    plist_dir = Path.home() / "Library" / "LaunchAgents"
+    plist_dir.mkdir(parents=True, exist_ok=True)
+    plist_path = plist_dir / f"{label}.plist"
+
+    plist_path.write_text(_launchd_plist(job, username))
+    subprocess.run(["launchctl", "bootout", f"gui/{_uid()}/{label}"], capture_output=True)
+    result = subprocess.run(
+        ["launchctl", "bootstrap", f"gui/{_uid()}", str(plist_path)], capture_output=True
+    )
+    return result.returncode == 0
+
+
+def _launchd_remove(job: Job) -> bool:
+    label = f"com.studyctl.{job.name}"
+    subprocess.run(["launchctl", "bootout", f"gui/{_uid()}/{label}"], capture_output=True)
+    plist = Path.home() / "Library" / "LaunchAgents" / f"{label}.plist"
+    if plist.exists():
+        plist.unlink()
+    return True
+
+
+def _launchd_list() -> list[dict]:
+    result = subprocess.run(["launchctl", "list"], capture_output=True, text=True)
+    jobs = []
+    for line in result.stdout.splitlines():
+        if "com.studyctl." in line:
+            parts = line.split()
+            jobs.append(
+                {
+                    "name": parts[2].replace("com.studyctl.", ""),
+                    "status": parts[0],
+                    "label": parts[2],
+                }
+            )
+    return jobs
+
+
+def _uid() -> int:
+    import os
+
+    return os.getuid()
+
+
+# ── Linux cron ─────────────────────────────────────────────────────────────
+
+
+def _cron_expression(job: Job) -> str:
+    if "every 2h" in job.schedule:
+        return "0 8-22/2 * * *"
+    elif "every 4h" in job.schedule:
+        return "30 8-22/4 * * *"
+    elif "daily" in job.schedule:
+        hour = 7
+        if "am" in job.schedule:
+            hour = int(job.schedule.split("daily")[1].strip().replace("am", "").strip())
+        return f"0 {hour} * * *"
+    return "0 * * * *"
+
+
+def _cron_line(job: Job) -> str:
+    home = str(Path.home())
+    cmd = job.command.replace("~", home)
+    log = f"{home}/.local/share/studyctl/logs/{job.name}.log"
+    path_dirs = [
+        f"{home}/.local/bin",
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+    ]
+    path = "PATH=" + ":".join(path_dirs)
+    cron = _cron_expression(job)
+    return f"{cron} {path} {cmd} >> {log} 2>&1 # studyctl:{job.name}"
+
+
+def _cron_install(job: Job) -> bool:
+    marker = f"# studyctl:{job.name}"
+    result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
+    existing = result.stdout if result.returncode == 0 else ""
+    # Remove old entry
+    lines = [line for line in existing.splitlines() if marker not in line]
+    lines.append(_cron_line(job))
+    subprocess.run(["crontab", "-"], input="\n".join(lines) + "\n", text=True, check=True)
+    return True
+
+
+def _cron_remove(job: Job) -> bool:
+    marker = f"# studyctl:{job.name}"
+    result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
+    if result.returncode != 0:
+        return True
+    lines = [line for line in result.stdout.splitlines() if marker not in line]
+    subprocess.run(["crontab", "-"], input="\n".join(lines) + "\n", text=True, check=True)
+    return True
+
+
+def _cron_list() -> list[dict]:
+    result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
+    if result.returncode != 0:
+        return []
+    jobs = []
+    for line in result.stdout.splitlines():
+        if "# studyctl:" in line:
+            name = line.split("# studyctl:")[1].strip()
+            jobs.append({"name": name, "cron": line.split("#")[0].strip()})
+    return jobs
+
+
+# ── Public API ─────────────────────────────────────────────────────────────
+
+
+def install_job(job: Job, username: str | None = None) -> bool:
+    Path.home().joinpath(".local/share/studyctl/logs").mkdir(parents=True, exist_ok=True)
+    username = username or Path.home().name
+    if _is_macos():
+        return _launchd_install(job, username)
+    return _cron_install(job)
+
+
+def remove_job(job: Job) -> bool:
+    if _is_macos():
+        return _launchd_remove(job)
+    return _cron_remove(job)
+
+
+def list_jobs() -> list[dict]:
+    if _is_macos():
+        return _launchd_list()
+    return _cron_list()
+
+
+def install_all(username: str | None = None) -> list[str]:
+    installed = []
+    for job in DEFAULT_JOBS:
+        if install_job(job, username):
+            installed.append(job.name)
+    return installed
+
+
+def remove_all() -> list[str]:
+    removed = []
+    for job in DEFAULT_JOBS:
+        if remove_job(job):
+            removed.append(job.name)
+    return removed

studyctl/services/__init__.py

@@ -0,0 +1,6 @@
+"""Service layer for studyctl.
+
+Framework-agnostic business logic that bridges CLI, web, and MCP
+interfaces to the underlying data layer. No click, fastapi, or other
+framework imports belong here.
+"""

studyctl/services/content.py

@@ -0,0 +1,39 @@
+"""Content pipeline service layer.
+
+Framework-agnostic wrappers for content pipeline operations. Used by
+CLI, future FastAPI web UI, and MCP server.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from studyctl.content import storage
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def list_courses(base_path: Path) -> list[dict]:
+    """List all courses under the content base path."""
+    return storage.list_courses(base_path)
+
+
+def get_course(base_path: Path, slug: str) -> Path:
+    """Get or create a course directory with standard subdirs."""
+    return storage.get_course_dir(base_path, slug)
+
+
+def slugify_title(title: str) -> str:
+    """Convert a book/course title to a filesystem-safe slug."""
+    return storage.slugify(title)
+
+
+def get_metadata(course_dir: Path) -> dict:
+    """Load course metadata (notebook IDs, syllabus state, generation history)."""
+    return storage.load_course_metadata(course_dir)
+
+
+def save_metadata(course_dir: Path, metadata: dict) -> None:
+    """Save course metadata atomically."""
+    storage.save_course_metadata(course_dir, metadata)

studyctl/services/review.py

@@ -0,0 +1,127 @@
+"""Service layer for review operations.
+
+Thin wrapper functions that delegate to :mod:`studyctl.review_db` and
+:mod:`studyctl.review_loader`.  This module is the bridge between
+consumer interfaces (CLI, web, MCP) and the data layer.
+
+Rules enforced by design:
+- NO framework imports (no click, no fastapi, no textual).
+- All functions are pure delegation with minimal orchestration.
+- Type annotations on every public function.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from studyctl import review_db, review_loader
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from studyctl.review_db import CardProgress
+    from studyctl.review_loader import Flashcard, QuizQuestion
+
+
+def get_cards(
+    course: str,
+    directory: Path,
+) -> tuple[list[Flashcard], list[QuizQuestion]]:
+    """Load flashcards and quiz questions for a course directory.
+
+    Uses :func:`review_loader.find_content_dirs` to locate the
+    ``flashcards/`` and ``quizzes/`` sub-directories, then delegates
+    to :func:`review_loader.load_flashcards` and
+    :func:`review_loader.load_quizzes`.
+
+    Args:
+        course: Course identifier (used for logging context, not filtering).
+        directory: Root directory that contains flashcard/quiz content.
+
+    Returns:
+        A tuple of (flashcards, quiz_questions).  Either list may be
+        empty if no content is found.
+    """
+    fc_dir, quiz_dir = review_loader.find_content_dirs(directory)
+
+    flashcards: list[Flashcard] = []
+    quizzes: list[QuizQuestion] = []
+
+    if fc_dir is not None:
+        flashcards = review_loader.load_flashcards(fc_dir)
+    if quiz_dir is not None:
+        quizzes = review_loader.load_quizzes(quiz_dir)
+
+    return flashcards, quizzes
+
+
+def record_review(
+    course: str,
+    card_type: str,
+    card_hash: str,
+    correct: bool,
+    response_time_ms: int | None = None,
+) -> None:
+    """Record a single card review result.
+
+    Delegates to :func:`review_db.record_card_review` which handles
+    SM-2 interval calculation and persistence.
+
+    Args:
+        course: Course identifier.
+        card_type: Either ``"flashcard"`` or ``"quiz"``.
+        card_hash: Stable hash identifying the card.
+        correct: Whether the answer was correct.
+        response_time_ms: Optional response time in milliseconds.
+    """
+    review_db.record_card_review(
+        course=course,
+        card_type=card_type,
+        card_hash=card_hash,
+        correct=correct,
+        response_time_ms=response_time_ms,
+    )
+
+
+def get_stats(course: str) -> dict:
+    """Get summary statistics for a course.
+
+    Returns a dict with keys: ``total_reviews``, ``unique_cards``,
+    ``due_today``, ``mastered``.
+
+    Args:
+        course: Course identifier.
+
+    Returns:
+        Statistics dictionary.  Returns zeroed stats if no reviews exist.
+    """
+    return review_db.get_course_stats(course=course)
+
+
+def get_due(course: str) -> list[CardProgress]:
+    """Get cards that are due for spaced-repetition review.
+
+    Args:
+        course: Course identifier.
+
+    Returns:
+        List of :class:`~studyctl.review_db.CardProgress` entries
+        whose ``next_review`` date is today or earlier, ordered by
+        earliest due first.
+    """
+    return review_db.get_due_cards(course=course)
+
+
+def get_wrong(course: str) -> set[str]:
+    """Get card hashes that were answered incorrectly in the most recent session.
+
+    Useful for "retry wrong answers" flows where the consumer wants to
+    re-present only the cards the learner got wrong.
+
+    Args:
+        course: Course identifier.
+
+    Returns:
+        Set of card hash strings.  Empty set if no sessions exist.
+    """
+    return review_db.get_wrong_hashes(course=course)